Audio Player React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Audio Player is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import AudioPlayer from @/components/ui/audio-player.

import { AudioPlayer } from "@/components/ui/audio-player"

export function Episode() {
  return (
    <AudioPlayer
      src="/demo/podcast.mp3"
      title="Sales tax for small businesses"
      subtitle="Summit Podcast · Ep. 12 · Sep 24, 2026"
      cover="/demo/mountains.jpg"
      downloadable
      labels={{ download: "Save episode" }}
    />
  )
}

export function VoiceNote() {
  return <AudioPlayer variant="compact" src="/demo/voice-message.mp3" labels={{ play: "Listen", pause: "Stop" }} />
}

Props

• src*
  string

  The audio file url. Decoding peaks needs the file on the same origin or served with CORS.

• titledefault ""
  ReactNode

  The card's title, and the lock-screen title while playing (when it is a string).

• subtitledefault ""
  ReactNode

  A muted line under the title (show, author, date); the lock-screen artist while playing.

• cover
  string

  Square artwork url for the card. It sits at 94% while paused and grows to full size while playing. Also the lock-screen artwork.

• leading
  ReactNode

  Compact only: an avatar or a mic icon before the play button, the chat look.

• variantdefault "card"
  "card" | "compact" | "minimal"

  card: cover, title, waveform and a controls row on a raised panel. compact: the voice message (play, bars, time, speed chip) for chat bubbles. minimal: play, a thin scrubbable bar and the time for lists and call logs.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  Colors the played bars and the play button. neutral is black in light mode and white in dark mode.

• colordefault ""
  string

  Any CSS color for the played bars and the play button; replaces the tone. The play icon turns black or white by lightness.

• sizedefault "md"
  "sm" | "md"

  Button sizes: md has a 40px play button in the card (32px compact and minimal), sm 32px (28px). Every button keeps a 44px touch target.

• radiusdefault "md"
  "none" | "sm" | "md" | "lg"

  Corner radius of the card surface (12 / 16 / 24px) and its cover.

• barCountdefault 0
  number

  How many bars. 0 fits as many as the width allows (barWidth + barGap each, remeasured on resize); a fixed count spreads over the width.

• barWidthdefault 3
  number

  Width of each bar in px.

• barGapdefault 2
  number

  Space between bars in px.

• barRadiusdefault 2
  number

  Corner radius of each bar in px.

• waveformHeightdefault 0
  number

  Height of the waveform in px. 0 is automatic: 40px in the card, 28px in the compact player.

• peaks
  number[]

  Precomputed bar heights from 0 to 1, any length (resampled to the bar count, max per bucket). Skips decoding.

• decodePeaksdefault true
  boolean

  Without peaks, fetch and decode the file with Web Audio once the player is on screen (one decode per file, cached), fading from placeholder bars to the real waveform. A CORS-blocked file stays on the placeholder bars. The file also exports a decodePeaks(src, count, { signal }) function that returns the same peaks as a Promise<number[]>, for precomputing them yourself.

• skipSecondsdefault 15
  number

  Seconds for the card's skip back / forward buttons and the lock-screen skip. 0 hides the buttons.

• rates
  number[]

  Playback speeds. Compact cycles through them on tap (default [1, 1.5, 2]); the card opens a menu (default MEDIA_RATES, 0.5 to 2). One entry hides the speed control.

• showVolumedefault "auto"
  "auto" | "always" | "never"

  The card's volume button and slider. auto hides it on touch screens, where people use the hardware keys.

• downloadabledefault false
  boolean

  A download button (card and minimal) that saves the file through file-export's downloadUrl and announces it.

• fileNamedefault ""
  string

  The downloaded file's name, sanitized, keeping the source's extension. Empty keeps the name from the url.

• exclusivedefault true
  boolean

  Starting this player pauses every other exclusive player on the page, so two voice notes never talk over each other.

• mediaSessiondefault true
  boolean

  While playing, sets the lock-screen metadata (title, subtitle, cover) and handles play, pause, seek back / forward and seek-to from the lock screen and headphones.

• preloaddefault "metadata"
  "none" | "metadata" | "auto"

  The audio element's preload. metadata loads the duration only; none shows --:-- until the first play.

• loopdefault false
  boolean

  Starts over at the end.

• localedefault ""
  string

  Formats the speed labels (1.5× in en-US, 1,5× in de-DE). Empty uses UIProvider, then the page language.

• onPlay
  () => void

  Playback started (passed to useMediaControls).

• onPause
  () => void

  Playback paused.

• onEnded
  () => void

  The recording reached its end (the play icon turns into replay).

• onError
  (error: MediaError | null) => void

  The file could not be loaded or played; the player shows the error row with a retry.

• onTimeUpdate
  (seconds: number) => void

  Whole seconds while playing and after seeks: resume positions, listening analytics.

• setApi
  (api: AudioPlayerApi) => void

  The media controls without the ref: playing, second, duration, progress (a motion value), play(), pause(), seek(seconds), seekBy, setRate... Called after mount and again when the state changes (at most once a second while playing), so it can go straight into state.

• labels
  Partial<AudioPlayerLabels>

  Every string: play "Play", pause "Pause", replay "Replay", loading "Loading", seek "Seek", skipBack(s) "Back {s} seconds", skipForward(s), speed "Speed", cancel "Cancel" (the speed sheet on phones), volume "Volume", mute "Mute", unmute "Unmute", download "Download", downloaded(name), error "The recording could not be played", retry "Try again", live "Live", position(current, total) "{current} of {total}". DEFAULT_AUDIO_PLAYER_LABELS holds the English set.

• classNames
  Partial<Record<AudioPlayerSlot, string>>

  Classes for the parts: audio, header, cover, meta, title, subtitle, leading, play, waveform, bar, time, controls, skipBack, skipForward, rate, volume, download, error, live.

Parts

FAQ

Used in

More React media components