Overview

Components

Libs

Resources

Audio Queue

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

Documentation

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. The provider manages the audio playback lifecycle using the useAudio() hook and synchronizes queue state with the audio element.

Changelog

2025-12-24 useAudio integration and improvements

Changed: Now uses useAudio() hook to access htmlAudio singleton
Improved: Better integration with audio provider lifecycle

Last updated 12/24/2025

Audio Provider Audio Track