Overview

Components

Libs

Resources

Audio Track

Track display components with list management and track information.

Documentation

Track components for displaying and managing audio tracks. These components support two modes:

Store mode: reads from and controls the global audio queue provided by the project's audio store.
Controlled mode: accepts an explicit list or single track for use in search results or external lists.

Installation


pnpm dlx shadcn@latest add @audio/track

Usage

import { AudioTrack, AudioTrackList } from "@/components/audio/track";

AudioTrack

Displays a single track with optional cover, metadata and playback controls. Use either:

trackId to render an item from the project's audio queue, or
track to render a provided track object.

// From queue by id
<AudioTrack trackId={track.id} />
 
// With explicit data
<AudioTrack track={customTrack} onClick={() => handlePlay(customTrack)} />

AudioTrackList

Renders a list of tracks. Pass tracks for a controlled list, otherwise the component renders the project queue.

Key features:

Text filtering via filterQuery or a custom filterFn.
Optional drag-and-drop (sortable) — reordering updates the queue only when not filtered and when tracks is not provided.
Per-item remove action and play/pause controls (configurable via props).

No tracks found

Try adding some tracks

// Default: renders project queue
<AudioTrackList onTrackSelect={(index) => console.log(index)} />
 
// Controlled: render custom set
<AudioTrackList tracks={searchResults} onTrackSelect={handleSelect} />

Grid Layout

No tracks found

Try adding some tracks

Sortable

No tracks found

Try adding some tracks

Sortable Grid

No tracks found

Try adding some tracks

API Reference

AudioTrack

Props

Prop	Type	Default	Description
`trackId`	`string \| number`	-	Load a track from the global queue (store mode). Do not use together with `track`.
`track`	`Track`	-	Render a provided track object (controlled mode). Do not use together with `trackId`.
`index`	`number`	-	Display index (one-based when shown).
`onClick`	`() => void`	-	Click handler invoked when the item is clicked.
`onRemove`	`(trackId: string) => void`	-	Called when the remove action is used. Receives the track id as string.
`showRemove`	`boolean`	`false`	Whether to show the remove (X) button. Hidden for the current playing track.
`showPlayPause`	`boolean`	`true`	Show play / pause control.
`showDragHandle`	`boolean`	`false`	Show a drag handle (used together with sortable lists).
`showCover`	`boolean`	`true`	Show album artwork (falls back to default icon).
`className`	`string`	-	Additional CSS classes.

Important Information:

Operating Modes: Use either trackId (store mode) or track (controlled mode). Both should not be used together. Store mode requires AudioProvider to be set up.
Track Display: Cover images are taken from track.artwork or track.images[0]. Live tracks show a "Live" badge and the duration is hidden. Live detection uses htmlAudio.isLive() from the useAudio() hook.

AudioTrackList

Props

Prop	Type	Default	Description
`tracks`	`Track[]`	-	Controlled list of tracks. When omitted the component reads from the global queue.
`onTrackSelect`	`(index: number, track?: Track) => void`	-	Called when a track is selected or played. In store mode the index is the queue index. In controlled mode the index refers to the provided `tracks` array.
`onTrackRemove`	`(trackId: string) => void`	-	Remove handler used by the per-item remove button.
`sortable`	`boolean`	`false`	Enable drag-and-drop reordering. Reordering will update the store queue only when not filtered and when `tracks` is not provided.
`showCover`	`boolean`	`true`	Show track cover image.
`variant`	`"default" \| "grid"`	`"default"`	Layout variant: stacked list or responsive grid.
`filterQuery`	`string`	-	Simple text filter (matches title or artist).
`filterFn`	`(track: Track) => boolean`	-	Custom filter function. When provided, `filterQuery` is ignored.
`emptyLabel`	`string`	`"No tracks found"`	Label shown when the list is empty.
`emptyDescription`	`string`	`"Try adding some tracks"`	Description shown in the empty state.
`className`	`string`	-	Additional CSS classes.

Store vs Controlled Mode: When tracks is omitted, the component reads from the global queue (store mode). When tracks is provided, it operates in controlled mode using the provided array.

Sortable Behavior: When sortable is enabled, reordering will update the store queue only when:

The list is not filtered (filterQuery and filterFn are not used)
The component is in store mode (tracks prop is not provided)

Keep sortable disabled while filtering to avoid confusing reordering behavior.

Examples

Store mode (main queue)

<AudioTrackList
  sortable
  onTrackSelect={(i) => console.log("play queue index", i)}
/>

Controlled mode (search results)

<AudioTrackList
  tracks={searchResults}
  variant="grid"
  onTrackSelect={(index, track) => addToQueue(track)}
/>

Filtering

<AudioTrackList filterQuery="jazz" />
// or
<AudioTrackList filterFn={(t) => t.genre === 'jazz'} />

With removal

<AudioTrackList onTrackRemove={(id) => removeFromQueue(id)} />

Notes

Important Information:

AudioProvider Requirement: AudioProvider (or the project's audio store) is required for store mode to work correctly. Make sure to wrap your app with the provider at the root level. The provider manages the audio playback state and lifecycle using the useAudio() hook, making it essential for all audio components.
Localization: If you localize strings (e.g., empty labels), pass emptyLabel and emptyDescription to the list component.

Changelog

2025-12-24 useAudio integration and live stream detection improvements

Changed: Now uses useAudio() hook to access htmlAudio singleton
Fixed: Live stream detection now correctly uses htmlAudio.isLive() method
Improved: Better handling of track duration for live vs. regular tracks

Last updated 12/24/2025

Audio Queue Audio Playback Speed