Registry / web-framework / vidstack

vidstack

JSON →
library0.6.15jsnpmunverified

Vidstack Player is a robust, customizable, and accessible framework and collection of UI components for building media players on the web. It is currently in version 0.6.15, designated as the 'latest' stable release, while active development continues on 'next' versions (e.g., 1.12.x). This indicates a slower stable release cadence but very frequent updates to the development branch. Vidstack differentiates itself by offering first-class TypeScript support, framework-agnostic usage (via Web Components) alongside dedicated React, Vue, Svelte, and Solid libraries, and a lean bundle size (54kB gzipped for core features). It supports various media providers including Audio, Video, HLS, DASH, YouTube, Vimeo, and Remotion, providing a single standard API across all. The library was battle-tested at Reddit, ensuring a mature architecture for managing complex media state, accessibility (WCAG 2.1 compliant), and cross-browser compatibility. It offers both headless components for full customization and production-ready default layouts, providing flexibility for developers to build custom UIs or quickly deploy a pre-built experience.

npm install vidstack
INSTALL
IMPORT
SIG · VIDSTACK
V
vidstack
web-frameworkjavascriptv0.6.15
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

MediaPlayer (Web Component)
✓ import 'vidstack/player'; // CSS for default layout import 'vidstack/player/styles/default/theme.css'; import 'vidstack/player/styles/default/layouts/video.css';
✗ import { MediaPlayer } from 'vidstack';
The core `vidstack` package exposes Web Components. The `MediaPlayer` element is defined via side-effect imports, making it available globally. For React, use `@vidstack/react`.
MediaPlayer (React)
✓ import { MediaPlayer, MediaProvider } from '@vidstack/react'; import { DefaultVideoLayout, defaultLayoutIcons } from '@vidstack/react/player/layouts/default';
✗ import { MediaPlayer } from 'vidstack'; // Incorrect for React
For React applications, use the dedicated `@vidstack/react` package. UI layouts and icons are imported from sub-paths.
Default Layout CSS (Base)
✓ import 'vidstack/player/styles/default/theme.css';
✗ import 'vidstack/styles/base.css'; // Old path before v0.6
Essential theme styles for the default layout. Specific layout styles (e.g., `video.css`, `audio.css`) should be imported separately.

This quickstart demonstrates a basic Vidstack video player in a React component, utilizing the `@vidstack/react` package and its default layout for quick setup. It includes event handling and custom styling.

import React, { useRef, useEffect } from 'react'; import { MediaPlayer, MediaProvider, type MediaPlayerInstance } from '@vidstack/react'; import { DefaultVideoLayout, defaultLayoutIcons } from '@vidstack/react/player/layouts/default'; // Import default layout styles import 'vidstack/player/styles/default/theme.css'; import 'vidstack/player/styles/default/layouts/video.css'; function VideoPlayer() { const player = useRef<MediaPlayerInstance>(null); useEffect(() => { // You can use the player API here once it's available if (player.current) { player.current.addEventListener('can-play', () => { console.log('Player is ready to play!'); // Example: Automatically play after 3 seconds if not already playing setTimeout(() => { if (player.current && !player.current.playing) { player.current.play(); } }, 3000); }); } }, []); return ( <div style={{ maxWidth: '800px', margin: 'auto' }}> <h1>My Awesome Video</h1> <MediaPlayer title="Sprite Fight" src="https://files.vidstack.io/sprite-fight/720p.mp4" poster="https://files.vidstack.io/sprite-fight/poster.webp" controls autoplay={false} crossOrigin="anonymous" onCanPlay={() => console.log('Media can play')} ref={player} style={{ '--media-brand': '#21C55E' }} > <MediaProvider /> <DefaultVideoLayout icons={defaultLayoutIcons} /> </MediaPlayer> <p>This is a basic Vidstack player integrated into a React component, demonstrating a self-hosted MP4 video with default UI controls.</p> </div> ); } export default VideoPlayer;
Debug
Known issues
breakingBreaking changes occurred in early v0.x releases (e.g., v0.4.0, v0.6.0). Notably, `vds-` prefixes were removed from events (e.g., `vds-play` became `play`) and Web Component elements were renamed (e.g., `<vds-hls>` to `<vds-hls-video>`). Readonly internal state on elements now uses `data-` attributes (e.g., `can-play` became `data-can-play`).
fix
Review the migration guides for specific versions if upgrading from older 0.x releases. Update event listeners, element names, and attribute access to align with current API conventions.
affects: <=0.6.0
gotchaThe `vidstack` package (core Web Components) and `@vidstack/react` (React wrapper) are distinct. Ensure you are importing components and hooks from the correct package for your environment, especially if mixing Web Components directly with a framework wrapper.
fix
For React projects, consistently use imports from `@vidstack/react` and its sub-packages. For vanilla JS or other frameworks, import Web Components via side-effects (e.g., `import 'vidstack/player';`).
affects: >=0.1.0
gotchaVidstack's stable release (0.6.15) is older, while significant active development occurs on `next` versions (e.g., 1.12.x). Features and API might differ between the `latest` stable and `next` branches, and `next` releases are still in Beta.
fix
For production, stick to the `latest` stable release unless you need features from `next` and are prepared for potential API changes. Monitor the GitHub repository for release announcements and changelogs if using `next`.
affects: >=0.6.0
gotchaThe `vidstack` NPM package, even when installed via `npm`, might at runtime load some assets (e.g., fonts, icons, specific provider libraries like hls.js if not bundled) from a CDN. This can be a concern for GDPR compliance or environments with strict content security policies.
fix
Audit network requests made by Vidstack in your application. For strict environments, consider self-hosting all assets or using bundler configurations to inline/copy external dependencies. Engage with the Vidstack community for fully offline solutions if critical.
affects: >=0.1.0
Errors
Common errors & fixes
Error: [vidstack] media is not ready - wait for can-play event
Attempting to call player methods (e.g., `play()`) before the media has loaded sufficiently and is ready for playback. This is often a timing issue with asynchronous media loading.
fix
Always await the `can-play` event or use the `onCanPlay` prop/event listener before invoking playback controls programmatically. For React, use `useEffect` with a ref to listen to player events.
Property 'vds-play' does not exist on type 'HTMLElement'. Did you mean 'play'?
Using deprecated `vds-` prefixes for event names or custom element attributes/properties after a breaking change in earlier 0.x versions.
fix
Update event listener names and component properties to remove the `vds-` prefix. For attributes reflecting internal state, use `data-` attributes (e.g., `data-can-play`).
No matching provider found for source: <URL>
The provided media source URL or type is not recognized by any of the available media providers (e.g., missing file extension, incorrect MIME type hint, or a provider like HLS/DASH not being available for its respective stream type).
fix
Ensure the `src` attribute or object includes a file extension (e.g., `.mp4`, `.m3u8`) or a `type` hint (e.g., `video/mp4`, `application/x-mpegurl`). Verify that necessary providers (like `hls.js` or `dash.js`) are correctly integrated if you are playing adaptive streams.
Upgrade
Version history
0.6.15latest on npm
Audit
Dependencies
hls.jsoptionalUsed by the HLS provider for HTTP Live Streaming playback in browsers without native support for Media Source Extensions (MSE). Vidstack can leverage an existing hls.js instance or load it dynamically.
dash.jsoptionalUsed by the DASH provider for Dynamic Adaptive Streaming over HTTP playback in browsers without native support for Media Source Extensions (MSE). Vidstack can leverage an existing dash.js instance or load it dynamically.
Agent activity
49 hits · last 30 days
node
44
OpenAI (training)
1
Resources
vidstack — npm install vidstack · libregistry