GitHub

Audio Track

PreviousNext

Track display components with list management and track information.

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

PropTypeDefaultDescription
trackIdstring | number-Load a track from the global queue (store mode). Do not use together with track.
trackTrack-Render a provided track object (controlled mode). Do not use together with trackId.
indexnumber-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.
showRemovebooleanfalseWhether to show the remove (X) button. Hidden for the current playing track.
showPlayPausebooleantrueShow play / pause control.
showDragHandlebooleanfalseShow a drag handle (used together with sortable lists).
showCoverbooleantrueShow album artwork (falls back to default icon).
classNamestring-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.

AudioTrackList

Props

PropTypeDefaultDescription
tracksTrack[]-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.
sortablebooleanfalseEnable drag-and-drop reordering. Reordering will update the store queue only when not filtered and when tracks is not provided.
showCoverbooleantrueShow track cover image.
variant"default" | "grid""default"Layout variant: stacked list or responsive grid.
filterQuerystring-Simple text filter (matches title or artist).
filterFn(track: Track) => boolean-Custom filter function. When provided, filterQuery is ignored.
emptyLabelstring"No tracks found"Label shown when the list is empty.
emptyDescriptionstring"Try adding some tracks"Description shown in the empty state.
classNamestring-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.
  • Localization: If you localize strings (e.g., empty labels), pass emptyLabel and emptyDescription to the list component.

Last updated 11/19/2025

Audio QueueSlider