Component reference
AudioPlayer
Browse and play locally bundled design-note episodes.
Preview
Live previewOptional six-digit hex. Clear to restore the preset. Check contrast with your brand color.
Changes apply to this preview only.
Find your rhythm
A moment to play
Width adapts to the available space
"use client";
import { useState } from "react";
import {
AudioPlayer,
Badge,
Button,
Card,
CardContent,
CardHeader,
CardTitle
} from "@pimolu/react";
export function DemoExample() {
const [track, setTrack] = useState("action-game");
return (
<div className="grid gap-6 sm:grid-cols-2">
<Card>
<CardHeader>
<Badge appearance="soft">Pimolu / Play</Badge>
<CardTitle>Find your rhythm</CardTitle>
</CardHeader>
<CardContent>
<AudioPlayer
key={track}
src={`/sounds/${track}.mp3`}
title={track === "action-game"
? "Action game"
: "Pixel art game"}
subtitle="Local soundtrack"
preload="none"
/>
<div className="mt-5 flex flex-wrap gap-3">
<Button
appearance="outline"
aria-pressed={track === "action-game"}
onClick={() => setTrack("action-game")}
>
Action game
</Button>
<Button
appearance="outline"
aria-pressed={track === "pixel-art-game"}
onClick={() => setTrack("pixel-art-game")}
>
Pixel art game
</Button>
</div>
</CardContent>
</Card>
<Card>
<CardHeader>
<CardTitle>A moment to play</CardTitle>
</CardHeader>
<CardContent>
<AudioPlayer
src="/sounds/pixel-art-game.mp3"
title="Pixel art game"
subtitle="Volume and timeline controls"
preload="none"
/>
</CardContent>
</Card>
</div>
);
}More examples
Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.
Episode
The title doubles as the accessible name of the player unless an explicit aria-label is given.
Minimal
Hide the volume slider and the time readout when space is tight; the mute button and the seek bar remain.
Controlled playback
`playing` and `onPlayingChange` let a parent coordinate several players, a transcript or an external transport bar.
Usage
Keep the playlist state and current track synchronized; avoid unsolicited audio playback.
API reference
Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.
PimoluAudioPlayerLabels
Type source| Name | Type | Default | Description |
|---|---|---|---|
player | string | undefined | — | Accessible name when neither `aria-label` nor `title` is given. |
play | string | undefined | "Play" | Defaults to "Play". |
pause | string | undefined | "Pause" | Defaults to "Pause". |
mute | string | undefined | "Mute" | Defaults to "Mute". |
unmute | string | undefined | "Unmute" | Defaults to "Unmute". |
volume | string | undefined | "Volume" | Defaults to "Volume". |
timeline | string | undefined | "Audio timeline" | Defaults to "Audio timeline". |
playerstring | undefinedNo default extracted.
Accessible name when neither `aria-label` nor `title` is given.
playstring | undefinedDefault: "Play"
Defaults to "Play".
pausestring | undefinedDefault: "Pause"
Defaults to "Pause".
mutestring | undefinedDefault: "Mute"
Defaults to "Mute".
unmutestring | undefinedDefault: "Unmute"
Defaults to "Unmute".
volumestring | undefinedDefault: "Volume"
Defaults to "Volume".
timelinestring | undefinedDefault: "Audio timeline"
Defaults to "Audio timeline".
PimoluAudioPlayerProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
srcRequired | string | — | Audio URL. |
title | string | undefined | — | Track name, also used as the accessible name of the player. |
subtitle | ReactNode | — | Artist, album or a short description under the title. |
playing | boolean | undefined | — | Controlled playback state. Omit to let the player own it. |
onPlayingChange | ((playing: boolean) => void) | undefined | — | Called whenever playback starts or stops. |
muted | boolean | undefined | false | Initial muted state when the player mounts. Defaults to false. |
defaultVolume | number | undefined | 1 | Initial volume, from 0 to 1. Defaults to 1. |
seekStep | number | undefined | 5 | Seconds skipped by ArrowLeft and ArrowRight. Defaults to 5. |
showVolume | boolean | undefined | true | Show the volume slider next to the mute button. Defaults to true. |
showTime | boolean | undefined | true | Show the current and total time. Defaults to true. |
className | string | undefined | — | Class applied to the player wrapper. |
audioClassName | string | undefined | — | Class applied to the native `<audio>`. |
labels | PimoluAudioPlayerLabels | undefined | — | Localizable control labels. |
onLoadedMetadata | ReactEventHandler<HTMLAudioElement> | undefined | — | Public Pimolu prop; see the source declaration for details. |
onTimeUpdate | ReactEventHandler<HTMLAudioElement> | undefined | — | Public Pimolu prop; see the source declaration for details. |
onPlay | ReactEventHandler<HTMLAudioElement> | undefined | — | Public Pimolu prop; see the source declaration for details. |
onPause | ReactEventHandler<HTMLAudioElement> | undefined | — | Public Pimolu prop; see the source declaration for details. |
onEnded | ReactEventHandler<HTMLAudioElement> | undefined | — | Public Pimolu prop; see the source declaration for details. |
onVolumeChange | ReactEventHandler<HTMLAudioElement> | undefined | — | Public Pimolu prop; see the source declaration for details. |
onDurationChange | ReactEventHandler<HTMLAudioElement> | undefined | — | Public Pimolu prop; see the source declaration for details. |
onChange | ChangeEventHandler<HTMLAudioElement, Element> | undefined | — | Standard React/HTML attribute. |
defaultValue | string | number | readonly string[] | undefined | — | Standard React/HTML attribute. |
style | CSSProperties | undefined | — | Standard React/HTML attribute. |
aria-label | string | undefined | — | Defines a string value that labels the current element. |
onClick | MouseEventHandler<HTMLAudioElement> | undefined | — | Standard React/HTML attribute. |
srcRequiredstringNo default extracted.
Audio URL.
titlestring | undefinedNo default extracted.
Track name, also used as the accessible name of the player.
subtitleReactNodeNo default extracted.
Artist, album or a short description under the title.
playingboolean | undefinedNo default extracted.
Controlled playback state. Omit to let the player own it.
onPlayingChange((playing: boolean) => void) | undefinedNo default extracted.
Called whenever playback starts or stops.
mutedboolean | undefinedDefault: false
Initial muted state when the player mounts. Defaults to false.
defaultVolumenumber | undefinedDefault: 1
Initial volume, from 0 to 1. Defaults to 1.
seekStepnumber | undefinedDefault: 5
Seconds skipped by ArrowLeft and ArrowRight. Defaults to 5.
showVolumeboolean | undefinedDefault: true
Show the volume slider next to the mute button. Defaults to true.
showTimeboolean | undefinedDefault: true
Show the current and total time. Defaults to true.
classNamestring | undefinedNo default extracted.
Class applied to the player wrapper.
audioClassNamestring | undefinedNo default extracted.
Class applied to the native `<audio>`.
labelsPimoluAudioPlayerLabels | undefinedNo default extracted.
Localizable control labels.
onLoadedMetadataReactEventHandler<HTMLAudioElement> | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
onTimeUpdateReactEventHandler<HTMLAudioElement> | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
onPlayReactEventHandler<HTMLAudioElement> | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
onPauseReactEventHandler<HTMLAudioElement> | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
onEndedReactEventHandler<HTMLAudioElement> | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
onVolumeChangeReactEventHandler<HTMLAudioElement> | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
onDurationChangeReactEventHandler<HTMLAudioElement> | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
onChangeChangeEventHandler<HTMLAudioElement, Element> | undefinedNo default extracted.
Standard React/HTML attribute.
defaultValuestring | number | readonly string[] | undefinedNo default extracted.
Standard React/HTML attribute.
styleCSSProperties | undefinedNo default extracted.
Standard React/HTML attribute.
aria-labelstring | undefinedNo default extracted.
Defines a string value that labels the current element.
onClickMouseEventHandler<HTMLAudioElement> | undefinedNo default extracted.
Standard React/HTML attribute.
Accessibility
- Name playback and seeking controls and offer a transcript for spoken audio.