brand-ui — MediaPlayer

import { MediaPlayer } from "@elabs-ai/components-ui";

Install

npm install @elabs-ai/components-tokens @elabs-ai/components-ui

Skipping the @source line is the most common first failure: Tailwind does not scan node_modules, so every component renders unstyled. The one-time wiring

Prompt for your coding agent

Paste it into Claude Code, Cursor, Codex or any other coding agent. Text in [brackets] is yours to fill in.

Add the brand-ui MediaPlayer component (from @elabs-ai/components-ui) to this project.

1. Read https://elabs-ai.com/llms.txt first: it maps every package and the rules. If you can use MCP servers, connect https://elabs-ai.com/mcp and use its search, docs and tokens tools. If not, run the same lookups in the terminal: `npx -y @elabs-ai/components-cli search "<what you need>"` and `npx -y @elabs-ai/components-cli docs <Component>`.
2. Look MediaPlayer up before writing code: `npx -y @elabs-ai/components-cli docs MediaPlayer` prints its real props, variants, what it pairs with and what to avoid.
3. If @elabs-ai/components-ui is not installed yet: `pnpm add @elabs-ai/components-tokens @elabs-ai/components-ui` (or `npm install @elabs-ai/components-tokens @elabs-ai/components-ui`). If this is the first brand-ui package in the project, wire it once: import `@elabs-ai/components-tokens/styles.css` plus the `themes/light.css` and `themes/dark.css` stylesheets in the CSS entry, add one Tailwind `@source` line per installed @elabs-ai package (Tailwind does not scan node_modules, so without it everything renders unstyled), and wrap the app root in `ThemeProvider` from `@elabs-ai/components-tokens`.
4. Use it here: [the screen or file, and what it should show]
5. Rules: use only @elabs-ai/components-* components and the semantic tokens — no raw colours, no raw font sizes, no arbitrary Tailwind values. Look up each component's real props with the docs tool before you use it; never guess a prop.
6. Done means: the typecheck passes, `npx -y @elabs-ai/components-cli audit src --strict` reports nothing, and you have opened the app and looked at every screen you touched in the light and the dark theme.

Avoid

Reaching for a third-party media engine — compose these parts.
The native `controls` attribute — it doubles the UI.

Works with

Contains

MediaPlayerElement
MediaPlayerViewport
MediaPlayerControls
MediaPlayerPlayButton
MediaPlayerSeekButton
MediaPlayerTimeSlider
MediaPlayerTime
MediaPlayerMuteButton
MediaPlayerVolumeSlider
MediaPlayerPlaybackRateMenu
MediaPlayerFullscreenButton
MediaPlayerPipButton
MediaPlayerCaptionsButton
MediaPlayerLoading
MediaPlayerError

Pairs with

Examples

4 live examples

Custom Video Layout

A custom video layout: title row above, overlay controls, captions toggle.

Headless Hook

`useMediaState` alone drives an entirely custom UI — no `MediaPlayer` parts.

Waveform

`MediaPlayerWaveform` is the scrubber drawn as the recording: `inline` in a control bar (the `Audio` row), `stage` where a picture would be, `strip` along the bottom of cover art (both inside a `MediaPlayerViewport`). Use it in place of `MediaPlayerTimeSlider`, never beside it.

API

`MediaPlayer`

Prop	Type	Description
`kind`required	`MediaKind`	Which element `MediaPlayerElement` renders.
`label`	`string`	The region's accessible name. Default "Audio player" / "Video player".
`keyboardShortcuts`	`boolean`	Handle the player keyboard map (Space/k, ←/→, j/l, ↑/↓, m, f, 0–9). Default `true`.

Also accepts: HTMLAttributes<HTMLDivElement>

`MediaPlayerCaptionsButton`

Prop	Type	Description
`size`	`IconButtonSize`	Icon-only size axis. Default `"icon"`.
`disabledReason`	`string`	Shown appended to the tooltip text, and — independently — exposed via `aria-describedby` through an `sr-only` node that is present whenever this prop is (i.e. it does NOT depend on the tooltip being open, and it is not rendered at all when there is no reason — so it can never be read as stray text), so assistive tech gets the reason even while the button is disabled (a disabled `<button>` still exposes its ARIA attributes; it just isn't focusable/hoverable itself, which is why the tooltip trigger wraps a focusable `<span>` instead — see the render below).
`side`	`ComponentProps<typeof TooltipContent>["side"]`	Tooltip placement. Default `"top"`.

Also accepts: MediaPlayerButtonProps

`MediaPlayerControls`

placement: docked (default)overlay

Also accepts: HTMLAttributes<HTMLDivElement>, VariantProps<typeof mediaPlayerControlsVariants>

`MediaPlayerElement`

fit: contain (default)cover

Also accepts: Omit<ComponentPropsWithoutRef<"video">, "controls">, VariantProps<typeof mediaPlayerElementVariants>

`MediaPlayerError`

Prop	Type	Description
`title`	`ReactNode`	Heading text.
`description`	`ReactNode`	Supporting description below the title.
`titleAs`	`"div" \| "h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6"`	Heading level for the panel's title (#328 convention). Set this to the level that correctly follows whatever heading precedes this panel in the document outline — e.g. `"h3"` inside a `ChartCard` whose own title is an `<h2>`. @default "h3"
`size`	`"sm" \| "md" \| "lg"`	Spinner size (loading kind only). @default "md"
`actions`	`ReactNode`	Primary / secondary action buttons.

Also accepts: Pick< StatePanelProps, "title" | "description" | "actions" | "size" | "titleAs" >, HTMLAttributes<HTMLDivElement>

`MediaPlayerFullscreenButton`

Prop	Type	Description
`size`	`IconButtonSize`	Icon-only size axis. Default `"icon"`.
`disabledReason`	`string`	Shown appended to the tooltip text, and — independently — exposed via `aria-describedby` through an `sr-only` node that is present whenever this prop is (i.e. it does NOT depend on the tooltip being open, and it is not rendered at all when there is no reason — so it can never be read as stray text), so assistive tech gets the reason even while the button is disabled (a disabled `<button>` still exposes its ARIA attributes; it just isn't focusable/hoverable itself, which is why the tooltip trigger wraps a focusable `<span>` instead — see the render below).
`side`	`ComponentProps<typeof TooltipContent>["side"]`	Tooltip placement. Default `"top"`.

Also accepts: MediaPlayerButtonProps

`MediaPlayerLoading`

Also accepts: HTMLAttributes<HTMLDivElement>

`MediaPlayerMuteButton`

Prop	Type	Description
`size`	`IconButtonSize`	Icon-only size axis. Default `"icon"`.
`disabledReason`	`string`	Shown appended to the tooltip text, and — independently — exposed via `aria-describedby` through an `sr-only` node that is present whenever this prop is (i.e. it does NOT depend on the tooltip being open, and it is not rendered at all when there is no reason — so it can never be read as stray text), so assistive tech gets the reason even while the button is disabled (a disabled `<button>` still exposes its ARIA attributes; it just isn't focusable/hoverable itself, which is why the tooltip trigger wraps a focusable `<span>` instead — see the render below).
`side`	`ComponentProps<typeof TooltipContent>["side"]`	Tooltip placement. Default `"top"`.

Also accepts: MediaPlayerButtonProps

`MediaPlayerPipButton`

Prop	Type	Description
`size`	`IconButtonSize`	Icon-only size axis. Default `"icon"`.
`disabledReason`	`string`	Shown appended to the tooltip text, and — independently — exposed via `aria-describedby` through an `sr-only` node that is present whenever this prop is (i.e. it does NOT depend on the tooltip being open, and it is not rendered at all when there is no reason — so it can never be read as stray text), so assistive tech gets the reason even while the button is disabled (a disabled `<button>` still exposes its ARIA attributes; it just isn't focusable/hoverable itself, which is why the tooltip trigger wraps a focusable `<span>` instead — see the render below).
`side`	`ComponentProps<typeof TooltipContent>["side"]`	Tooltip placement. Default `"top"`.

Also accepts: MediaPlayerButtonProps

`MediaPlayerPlayButton`

Prop	Type	Description
`size`	`IconButtonSize`	Icon-only size axis. Default `"icon"`.
`disabledReason`	`string`	Shown appended to the tooltip text, and — independently — exposed via `aria-describedby` through an `sr-only` node that is present whenever this prop is (i.e. it does NOT depend on the tooltip being open, and it is not rendered at all when there is no reason — so it can never be read as stray text), so assistive tech gets the reason even while the button is disabled (a disabled `<button>` still exposes its ARIA attributes; it just isn't focusable/hoverable itself, which is why the tooltip trigger wraps a focusable `<span>` instead — see the render below).
`side`	`ComponentProps<typeof TooltipContent>["side"]`	Tooltip placement. Default `"top"`.

Also accepts: MediaPlayerButtonProps

`MediaPlayerPlaybackRateMenu`

Prop	Type	Description
`rates`	`readonly number[]`	Offered speeds. Default `[0.5, 0.75, 1, 1.25, 1.5, 2]`.

Also accepts: Omit< ComponentPropsWithoutRef<typeof Button>, "children" | "asChild" >

`MediaPlayerSeekButton`

Prop	Type	Description
`offset`required	`number`	Seconds to jump; negative seeks backward.
`size`	`IconButtonSize`	Icon-only size axis. Default `"icon"`.
`disabledReason`	`string`	Shown appended to the tooltip text, and — independently — exposed via `aria-describedby` through an `sr-only` node that is present whenever this prop is (i.e. it does NOT depend on the tooltip being open, and it is not rendered at all when there is no reason — so it can never be read as stray text), so assistive tech gets the reason even while the button is disabled (a disabled `<button>` still exposes its ARIA attributes; it just isn't focusable/hoverable itself, which is why the tooltip trigger wraps a focusable `<span>` instead — see the render below).
`side`	`ComponentProps<typeof TooltipContent>["side"]`	Tooltip placement. Default `"top"`.

Also accepts: MediaPlayerButtonProps

`MediaPlayerTime`

Prop	Type	Description
`mode`	`"current" \| "duration" \| "remaining"`	`current` playhead · `duration` total · `remaining` time left (prefixed "-"). Default `current`.

Also accepts: HTMLAttributes<HTMLSpanElement>

`MediaPlayerTimeSlider`

Prop	Type	Description
`thumbProps`	`SliderThumbProps \| SliderThumbProps[]`	Escape hatch spread onto the thumb LAST — for `data-*`/`style`/etc, or to deliberately override `aria-label`/`aria-labelledby`/`aria-valuetext` (an explicit key here always wins over the matching top-level prop). The six keys that MAKE the element a slider are ignored on purpose: `role`, `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, `aria-orientation` and `tabIndex`. Radix derives every one of them from the slider's live state and spreads consumer props AFTER its own, so passing them here would silently destroy the widget (a wrong `aria-valuenow` mis-announces the value; `role`/`tabIndex` make it unreachable). Change the VALUE (`value`/`min`/`max`/`orientation`/ `disabled`) on `Slider` instead; use `aria-valuetext` to change how the value is spoken. Radix renders one thumb per element of `value`/`defaultValue` — pass a single object to apply the same props to every thumb (the historical single-thumb shape, unchanged), or an ARRAY to give each thumb its own props, indexed positionally against `value`/`defaultValue` (#398). A missing array slot falls back to no per-thumb override for that thumb.

Theming

The tokens each state resolves to. Change the token and every theme follows.

State	Token
paused	`data-paused on the root`
controls	`data-controls=visible\|hidden (hidden only when overlaid)`