Overview

Components

Libs

Resources

Audio Queue

Composable queue management components with shuffle, repeat, and track selection.

A comprehensive queue management system. Includes shuffle, repeat modes, track selection, search, and drag-and-drop reordering.

Installation


pnpm dlx shadcn@latest add @audio/queue

Usage

Import the components you need:

import {
  AudioQueue,
  AudioQueueButton,
  AudioQueuePreferences,
  AudioQueueRepeatMode,
  AudioQueueShuffle,
} from "@/components/audio/queue"

Basic Queue

The AudioQueue component opens a dialog showing the current queue with search functionality and track selection.

<AudioPlayer>
  <AudioPlayerControlBar>
    <AudioQueue />
  </AudioPlayerControlBar>
</AudioPlayer>

Queue with Shuffle and Repeat

Use this when you want quick access to shuffle and repeat controls. The toggle buttons provide fast switching between modes.

<AudioPlayer>
  <AudioPlayerControlBar>
    <AudioQueueShuffle />
    <AudioQueueRepeatMode />
    <AudioQueue />
  </AudioPlayerControlBar>
</AudioPlayer>

Queue with Preferences

Use this when you want a compact interface with all queue settings in a dropdown menu. Ideal for space-constrained layouts.

<AudioPlayer>
  <AudioPlayerControlBar>
    <AudioQueuePreferences />
    <AudioQueue />
  </AudioPlayerControlBar>
</AudioPlayer>

Queue with All Controls

Use this when you want both quick access buttons and a preferences menu. Provides the most comprehensive queue management interface.

<AudioPlayer tracks={tracks}>
  <AudioPlayerControlBar>
    <AudioQueueShuffle />
    <AudioQueueRepeatMode />
    <AudioQueuePreferences />
    <AudioQueue />
  </AudioPlayerControlBar>
</AudioPlayer>

API Reference

AudioQueue

A dialog component that displays the current queue and allows track selection, search, and reordering.

Props

Prop	Type	Default	Description
`onTrackSelect`	`(index: number) => void`	-	Callback function to handle track selection. Receives the index of the selected track.
`searchPlaceholder`	`string`	`"Search for a track..."`	Placeholder text for the search input.
`emptyLabel`	`string`	`"No tracks found"`	Label to display when the queue is empty.
`emptyDescription`	`string`	`"Try searching for a different track"`	Description to display when the queue is empty.

Features

Search: Filter tracks by title or artist
Track selection: Click to play or pause current track
Drag and drop: Reorder tracks when not searching
Remove tracks: Remove individual tracks from queue
Clear queue: Button to clear all tracks

Search and Drag-and-Drop: Search functionality filters tracks by title or artist. Track reordering is automatically disabled when search is active to prevent confusion. The queue dialog automatically closes when a track is selected.

Example

<AudioQueue
  onTrackSelect={(index) => {
    console.log("Selected track at index:", index);
  }}
  searchPlaceholder="Search tracks..."
  emptyLabel="Queue is empty"
  emptyDescription="Add tracks to the queue to see them here"
/>

AudioQueueButton

A button component with optional tooltip support, used internally by queue components.

Props

Prop	Type	Default	Description
`tooltip`	`boolean`	`false`	Whether to show a tooltip.
`tooltipLabel`	`string`	-	Tooltip text to display.

Example

<AudioQueueButton
  tooltip
  tooltipLabel="Open queue"
  variant="outline"
  size="icon"
>
  <ListMusicIcon />
</AudioQueueButton>

AudioQueueRepeatMode

A toggle button that cycles through repeat modes: none, one, all.

Props

Inherits all props from Toggle component.

Behavior

None: No repeat (default)
One: Repeat current track indefinitely
All: Repeat entire queue

The button shows different icons based on the current mode:

RepeatIcon for "all" mode
Repeat1Icon for "one" mode
No icon when disabled (none mode)

Example

<AudioQueueRepeatMode />

AudioQueueShuffle

A toggle button that enables/disables shuffle mode. When enabled, the queue is shuffled randomly.

Props

Inherits all props from Toggle component (except onPressedChange).

Behavior

When enabled: Queue is shuffled randomly
When disabled: Queue maintains original order

The shuffle state persists until manually disabled.

State Persistence: The shuffle and repeat mode states are persisted to localStorage and will be restored when the app reloads.

Example

<AudioQueueShuffle />

AudioQueuePreferences

A dropdown menu that combines repeat mode and insert mode controls in a compact interface.

Props

Inherits all props from AudioQueueButton component.

Features

Repeat mode selection: None, One, All
Insert mode selection: First, Last, After Current

Insert Modes

First: New tracks are added at the beginning of the queue
Last: New tracks are added at the end of the queue (default)
After Current: New tracks are added after the currently playing track

Insert Mode Behavior: The insert mode determines where new tracks are added to the queue when using addToQueue. This setting persists across sessions via localStorage.

Example

<AudioQueuePreferences />

Integration with AudioPlayer

Queue components are designed to work seamlessly with the AudioPlayer component:

<AudioPlayer>
  <AudioPlayerControlBar>
    <AudioPlayerControlGroup>
      <AudioPlayerPlay />
      <AudioPlayerSeekBar />
      <AudioPlayerTimeDisplay />
    </AudioPlayerControlGroup>
    <AudioPlayerControlGroup>
      <AudioQueueShuffle />
      <AudioQueueRepeatMode />
      <AudioQueue />
    </AudioPlayerControlGroup>
  </AudioPlayerControlBar>
</AudioPlayer>

Notes

AudioProvider Requirement: AudioProvider (or the project's audio store) is required for queue components to work correctly. All components read from and update the global audio store state.

Last updated 11/19/2025

Audio Player Audio Track