Component reference
VideoPlayer
Play the bundled Pimolu tour with captions.
Preview
Live previewOptional six-digit hex. Clear to restore the preset. Check contrast with your brand color.
Changes apply to this preview only.
Width adapts to the available space
"use client";
import { VideoPlayer } from "@pimolu/react";
const TOUR_SRC = "/demos/media/pimolu-tour.webm";
const TOUR_POSTER = "/images/pimolu-atmosphere.webp";
function Captions() {
return (
<track
kind="captions"
src="/demos/media/pimolu-tour.en.vtt"
srcLang="en"
label="English"
/>
);
}
export function DemoExample() {
return (
<VideoPlayer
src={TOUR_SRC}
poster={TOUR_POSTER}
aspectRatio={16 / 9}
captions={<Captions />}
aria-label="Pimolu product tour"
labels={{
timeline: "Product tour timeline",
}}
/>
);
}More examples
Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.
Controlled playback
The parent owns `playing`. Every media event and control click reports through `onPlayingChange`, so an external action bar can drive the same playback state.
Muted autoplay and a square frame
Muted autoplay is the only autoplay browsers reliably allow. `aspectRatio` can reserve any frame; `showFullscreen={false}` keeps the control bar minimal.
Course lesson
A real-world composition: the player sits above the lesson notes, with a localized control bar and a captions track.
Usage
Serve real media with suitable codecs and caption tracks; handle unavailable playback explicitly.
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.
PimoluVideoPlayerLabels
Type source| Name | Type | Default | Description |
|---|---|---|---|
player | string | undefined | "Video player" | Accessible name of the whole player region. Defaults to "Video player". |
play | string | undefined | "Play" | Name of the play button. Defaults to "Play". |
pause | string | undefined | "Pause" | Name of the pause button. Defaults to "Pause". |
mute | string | undefined | "Mute" | Name of the mute button while the sound is on. Defaults to "Mute". |
unmute | string | undefined | "Unmute" | Name of the mute button while the sound is off. Defaults to "Unmute". |
volume | string | undefined | "Volume" | Name of the volume slider. Defaults to "Volume". |
timeline | string | undefined | "Video timeline" | Name of the timeline slider. Defaults to "Video timeline". |
fullscreen | string | undefined | "Enter fullscreen" | Name of the fullscreen button. Defaults to "Enter fullscreen". |
exitFullscreen | string | undefined | "Exit fullscreen" | Name of the fullscreen button while fullscreen. Defaults to "Exit fullscreen". |
playerstring | undefinedDefault: "Video player"
Accessible name of the whole player region. Defaults to "Video player".
playstring | undefinedDefault: "Play"
Name of the play button. Defaults to "Play".
pausestring | undefinedDefault: "Pause"
Name of the pause button. Defaults to "Pause".
mutestring | undefinedDefault: "Mute"
Name of the mute button while the sound is on. Defaults to "Mute".
unmutestring | undefinedDefault: "Unmute"
Name of the mute button while the sound is off. Defaults to "Unmute".
volumestring | undefinedDefault: "Volume"
Name of the volume slider. Defaults to "Volume".
timelinestring | undefinedDefault: "Video timeline"
Name of the timeline slider. Defaults to "Video timeline".
fullscreenstring | undefinedDefault: "Enter fullscreen"
Name of the fullscreen button. Defaults to "Enter fullscreen".
exitFullscreenstring | undefinedDefault: "Exit fullscreen"
Name of the fullscreen button while fullscreen. Defaults to "Exit fullscreen".
PimoluVideoPlayerProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
src | string | undefined | — | Video URL. Sources may also be provided through `captions`/native markup. |
captions | ReactNode | — | Captions and subtitles: typically one or more `<track>` elements. They are rendered inside `<video>`, where the browser expects them. |
fallback | ReactNode | — | Native fallback content rendered inside `<video>`. |
poster | string | undefined | — | Poster shown before the first frame. |
playing | boolean | undefined | — | Controlled playback state. Omit to let the player own it. Changing the prop calls `play()` or `pause()` on the media element. |
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. |
showFullscreen | boolean | undefined | true | Render the fullscreen button when the browser supports it. Defaults to true. |
aspectRatio | string | number | undefined | — | Aspect ratio reserved for the video box, e.g. `16 / 9`. |
className | string | undefined | — | Class applied to the player wrapper. |
videoClassName | string | undefined | — | Class applied to the native `<video>`. |
labels | PimoluVideoPlayerLabels | undefined | — | Localizable control labels. |
onLoadedMetadata | ReactEventHandler<HTMLVideoElement> | undefined | — | Called after the media metadata loads. |
onTimeUpdate | ReactEventHandler<HTMLVideoElement> | undefined | — | Called while the playhead moves. |
onPlay | ReactEventHandler<HTMLVideoElement> | undefined | — | Called when the media starts playing. |
onPause | ReactEventHandler<HTMLVideoElement> | undefined | — | Called when the media pauses. |
onEnded | ReactEventHandler<HTMLVideoElement> | undefined | — | Called when the media ends. |
onVolumeChange | ReactEventHandler<HTMLVideoElement> | undefined | — | Called when the volume or muted state changes. |
onDurationChange | ReactEventHandler<HTMLVideoElement> | undefined | — | Called when the duration becomes known or changes. |
onClick | ReactEventHandler<HTMLVideoElement> | undefined | — | Called when the video surface is clicked. Playback still toggles unless prevented. |
onChange | ChangeEventHandler<HTMLVideoElement, 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. |
srcstring | undefinedNo default extracted.
Video URL. Sources may also be provided through `captions`/native markup.
captionsReactNodeNo default extracted.
Captions and subtitles: typically one or more `<track>` elements. They are rendered inside `<video>`, where the browser expects them.
fallbackReactNodeNo default extracted.
Native fallback content rendered inside `<video>`.
posterstring | undefinedNo default extracted.
Poster shown before the first frame.
playingboolean | undefinedNo default extracted.
Controlled playback state. Omit to let the player own it. Changing the prop calls `play()` or `pause()` on the media element.
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.
showFullscreenboolean | undefinedDefault: true
Render the fullscreen button when the browser supports it. Defaults to true.
aspectRatiostring | number | undefinedNo default extracted.
Aspect ratio reserved for the video box, e.g. `16 / 9`.
classNamestring | undefinedNo default extracted.
Class applied to the player wrapper.
videoClassNamestring | undefinedNo default extracted.
Class applied to the native `<video>`.
labelsPimoluVideoPlayerLabels | undefinedNo default extracted.
Localizable control labels.
onLoadedMetadataReactEventHandler<HTMLVideoElement> | undefinedNo default extracted.
Called after the media metadata loads.
onTimeUpdateReactEventHandler<HTMLVideoElement> | undefinedNo default extracted.
Called while the playhead moves.
onPlayReactEventHandler<HTMLVideoElement> | undefinedNo default extracted.
Called when the media starts playing.
onPauseReactEventHandler<HTMLVideoElement> | undefinedNo default extracted.
Called when the media pauses.
onEndedReactEventHandler<HTMLVideoElement> | undefinedNo default extracted.
Called when the media ends.
onVolumeChangeReactEventHandler<HTMLVideoElement> | undefinedNo default extracted.
Called when the volume or muted state changes.
onDurationChangeReactEventHandler<HTMLVideoElement> | undefinedNo default extracted.
Called when the duration becomes known or changes.
onClickReactEventHandler<HTMLVideoElement> | undefinedNo default extracted.
Called when the video surface is clicked. Playback still toggles unless prevented.
onChangeChangeEventHandler<HTMLVideoElement, 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.
Accessibility
- Provide captions, keyboard-operable controls and a transcript for essential spoken content.