Add this component

npx zentauri-ui add audio-player

Accessibility notes

Keyboard accessible by default with semantic markup, visible focus treatment, and tokenized states. Add descriptive labels for icon-only or decorative usage.

Dependency notes

Check Installation for shared peers. This component keeps styling in Tailwind classes and the --zui-* token contract.

Media

Audio Player for media playback

Use the Audio Player when you need inline media playback — podcast episodes, voice memos, music previews. The compound component exposes sub-components for the progress bar, time display, and volume, plus a `useAudioPlayer` hook so you can wire Play/Pause/Reset buttons anywhere in the tree.

Audio Player variants playground

Pick an appearance, size, and shape to preview the player live. Toggle Show output / Show code and the snippet updates to match the selected variant. The demo loads a real audio stream — hit Play to hear it.

Appearance

Size

Shape

All appearances

Every shipped appearance token at a glance. Click any card to load it into the playground above.

Audio Player API

Generated from the package prop types and variant definitions.

AudioPlayer

AudioPlayerProps

Variants

Prop	Type	Default
appearance	`bluecrimsoncyandefaultdestructiveelectricemeraldforestgradient-bluegradient-greengradient-indigogradient-orange`+27	default
shape	`flatpillrounded`	rounded
size	`lgmdsm`	md

Behavior

Prop	Type	Default
autoPlay	`boolean \| undefined`	none
loop	`boolean \| undefined`	none
onEnded	`(ReactEventHandler<HTMLDivElement> & (() => void)) \| undefined`	none
onPause	`(ReactEventHandler<HTMLDivElement> & (() => void)) \| undefined`	none
onPlay	`(ReactEventHandler<HTMLDivElement> & (() => void)) \| undefined`	none
onTimeUpdate	`(ReactEventHandler<HTMLDivElement> & ((currentTime: number, duration: number) => void)) \| undefined`	none
src*	`string`	none

Content

Prop	Type	Default
children	`ReactNode`	none

Inherited HTML props

Prop	Type	Default
className	`string \| undefined`	none
id	`string \| undefined`	none
onClick	`MouseEventHandler<HTMLDivElement> \| undefined`	none
style	`CSSProperties \| undefined`	none
title	`string \| undefined`	none

AudioPlayerProgress

AudioPlayerProgressProps

Inherited HTML props

Prop	Type	Default
className	`string \| undefined`	none
id	`string \| undefined`	none
onClick	`MouseEventHandler<HTMLDivElement> \| undefined`	none
style	`CSSProperties \| undefined`	none
title	`string \| undefined`	none

AudioPlayerTime

AudioPlayerTimeProps

Behavior

Prop	Type	Default
format	`((seconds: number) => string) \| undefined`	none

Inherited HTML props

Prop	Type	Default
className	`string \| undefined`	none

AudioPlayerVariant

AudioPlayerVariantProps

Behavior

Prop	Type	Default
appearance	'default' \| 'blue' \| 'cyan' \| 'green' \| 'lime' \| 'mint' \| 'ocean' \| 'sapphire' \| 'lavender' \| 'ruby' \| 'red' \| 'slate' \| 'zinc' \| 'royal' \| 'electric' \| 'forest' \| 'sunset' \| 'magenta' \| 'crimson' \| 'sky' \| 'rose' \| 'purple' \| 'pink' \| 'orange' \| 'yellow' \| 'teal' \| 'indigo' \| 'emerald' \| 'gradient-blue' \| 'gradient-green' \| 'gradient-red' \| 'gradient-yellow' \| 'gradient-purple' \| 'gradient-teal' \| 'gradient-indigo' \| 'gradient-pink' \| 'gradient-orange' \| 'secondary' \| 'destructive' \| null \| undefined	none
shape	`'rounded' \| 'flat' \| 'pill' \| null \| undefined`	none
size	`'md' \| 'sm' \| 'lg' \| null \| undefined`	none

AudioPlayerVolume

AudioPlayerVolumeProps

Inherited HTML props

Prop	Type	Default
className	`string \| undefined`	none
id	`string \| undefined`	none
onClick	`MouseEventHandler<HTMLDivElement> \| undefined`	none
style	`CSSProperties \| undefined`	none
title	`string \| undefined`	none

What it does

AudioPlayer wraps an HTML5 `<audio>` element and surfaces its state through React context. Sub-components (`AudioPlayerProgress`, `AudioPlayerTime`, `AudioPlayerVolume`) auto-connect to that context — no prop drilling needed.

The `useAudioPlayer()` hook lets you attach controls to buttons placed anywhere inside the `<AudioPlayer>` tree.

Composition and API

All visual variants live in the `appearance` prop. Combine with `size` (sm/md/lg) and `shape` (flat/rounded/pill) to match your layout.

For headless usage, wrap your custom UI in `<AudioPlayer src="...">` and drive it entirely through `useAudioPlayer()`.

Common use cases

Embed podcast or voice note playback in article pages.
Add music preview controls to a streaming catalog.
Build custom waveform players over the hook controls.
Drive keyboard-accessible scrubbing via the progress bar component.

Accessibility

The progress slider carries `role="slider"`, `aria-valuenow`, `aria-valuemin`, and `aria-valuemax`. Arrow keys scrub 1 % per step; Home and End jump to the start and end.

Volume has the same slider semantics. The mute toggle button carries a descriptive `aria-label` that updates with state.

Next.js integration notes

All sub-components carry `"use client"` through the entry point, so they are safe to import from server components. Set `NEXT_PUBLIC_SITE_URL` for correct canonical and OG URLs on deploy.

FAQ

Can I wire external buttons to the player?

Yes — call `useAudioPlayer()` inside any child of `<AudioPlayer>` to get `play`, `pause`, `toggle`, and `reset` actions and attach them to any element.

Does it work with Next.js App Router?

Yes. The component uses a `"use client"` directive internally, so you can import it directly inside server components — Next.js will handle the client boundary automatically.

Is the progress bar keyboard-accessible?

Yes. `AudioPlayerProgress` carries `role="slider"` with arrow-key scrubbing (1 % per step), Home/End for extremes, and a visible focus ring.