{"id":14229,"library":"vidstack","title":"Vidstack Media Player","description":"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.","status":"active","version":"0.6.15","language":"javascript","source_language":"en","source_url":"https://github.com/vidstack/vidstack","tags":["javascript","accessible","audio","customizable","dailymotion","elements","extensible","file","framework-agnostic","typescript"],"install":[{"cmd":"npm install vidstack","lang":"bash","label":"npm"},{"cmd":"yarn add vidstack","lang":"bash","label":"yarn"},{"cmd":"pnpm add vidstack","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used 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.","package":"hls.js","optional":true},{"reason":"Used 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.","package":"dash.js","optional":true}],"imports":[{"note":"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`.","wrong":"import { MediaPlayer } from 'vidstack';","symbol":"MediaPlayer (Web Component)","correct":"import 'vidstack/player';\n// CSS for default layout\nimport 'vidstack/player/styles/default/theme.css';\nimport 'vidstack/player/styles/default/layouts/video.css';"},{"note":"For React applications, use the dedicated `@vidstack/react` package. UI layouts and icons are imported from sub-paths.","wrong":"import { MediaPlayer } from 'vidstack'; // Incorrect for React","symbol":"MediaPlayer (React)","correct":"import { MediaPlayer, MediaProvider } from '@vidstack/react';\nimport { DefaultVideoLayout, defaultLayoutIcons } from '@vidstack/react/player/layouts/default';"},{"note":"Essential theme styles for the default layout. Specific layout styles (e.g., `video.css`, `audio.css`) should be imported separately.","wrong":"import 'vidstack/styles/base.css'; // Old path before v0.6","symbol":"Default Layout CSS (Base)","correct":"import 'vidstack/player/styles/default/theme.css';"}],"quickstart":{"code":"import React, { useRef, useEffect } from 'react';\nimport { MediaPlayer, MediaProvider, type MediaPlayerInstance } from '@vidstack/react';\nimport { DefaultVideoLayout, defaultLayoutIcons } from '@vidstack/react/player/layouts/default';\n\n// Import default layout styles\nimport 'vidstack/player/styles/default/theme.css';\nimport 'vidstack/player/styles/default/layouts/video.css';\n\nfunction VideoPlayer() {\n  const player = useRef<MediaPlayerInstance>(null);\n\n  useEffect(() => {\n    // You can use the player API here once it's available\n    if (player.current) {\n      player.current.addEventListener('can-play', () => {\n        console.log('Player is ready to play!');\n        // Example: Automatically play after 3 seconds if not already playing\n        setTimeout(() => {\n          if (player.current && !player.current.playing) {\n            player.current.play();\n          }\n        }, 3000);\n      });\n    }\n  }, []);\n\n  return (\n    <div style={{ maxWidth: '800px', margin: 'auto' }}>\n      <h1>My Awesome Video</h1>\n      <MediaPlayer\n        title=\"Sprite Fight\"\n        src=\"https://files.vidstack.io/sprite-fight/720p.mp4\"\n        poster=\"https://files.vidstack.io/sprite-fight/poster.webp\"\n        controls\n        autoplay={false}\n        crossOrigin=\"anonymous\"\n        onCanPlay={() => console.log('Media can play')}\n        ref={player}\n        style={{ '--media-brand': '#21C55E' }}\n      >\n        <MediaProvider />\n        <DefaultVideoLayout icons={defaultLayoutIcons} />\n      </MediaPlayer>\n      <p>This is a basic Vidstack player integrated into a React component, demonstrating a self-hosted MP4 video with default UI controls.</p>\n    </div>\n  );\n}\n\nexport default VideoPlayer;\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Breaking 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`).","severity":"breaking","affected_versions":"<=0.6.0"},{"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';`).","message":"The `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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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`.","message":"Vidstack'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.","severity":"gotcha","affected_versions":">=0.6.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"search_vec":"'0.6.15':30 '1.12':45 '2.1':137 '54kb':92 'access':11,135,175 'across':116 'activ':38 'agnost':74,184 'alongsid':79 'api':115 'architectur':129 'audio':103,176 'battl':122 'battle-test':121 'branch':61 'browser':142 'build':19,163 'built':172 'bundl':90 'cadenc':53 'class':69 'collect':14 'compat':143 'complex':132 'compliant':138 'compon':17,78,148 'continu':40 'core':95 'cross':141 'cross-brows':140 'current':27 'custom':151,164 'customiz':9,177 'dailymot':178 'dash':106 'dedic':80 'default':156 'deploy':168 'design':31 'develop':39,60,161 'differenti':63 'e.g':44 'element':179 'ensur':126 'experi':173 'extens':180 'featur':96 'file':181 'first':68 'first-class':67 'flexibl':159 'framework':12,73,183 'framework-agnost':72,182 'frequent':56 'full':150 'gzip':93 'headless':147 'hls':105 'includ':102 'indic':48 'javascript':174 'latest':34 'layout':157 'lean':89 'librari':86,119 'manag':131 'matur':128 'media':2,20,100,133 'next':42 'offer':66,145 'player':3,5,21 'pre':171 'pre-built':170 'product':154 'production-readi':153 'provid':101,111,158 'quick':167 'react':81 'readi':155 'reddit':125 'releas':36,52 'remot':110 'robust':8 'singl':113 'size':91 'slower':50 'solid':85 'stabl':35,51 'standard':114 'state':134 'support':71,98 'svelt':83 'test':123 'typescript':70,185 'ui':16,165 'updat':57 'usag':75 'various':99 'version':29,43 'via':76 'video':104 'vidstack':1,4,62 'vimeo':108 'vue':82 'wcag':136 'web':24,77 'x':46 'youtub':107","created_at":"2026-04-20T01:58:36.633515+00:00","updated_at":"2026-04-20T01:58:36.633515+00:00","problems":[{"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.","cause":"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.","error":"Error: [vidstack] media is not ready - wait for can-play event"},{"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`).","cause":"Using deprecated `vds-` prefixes for event names or custom element attributes/properties after a breaking change in earlier 0.x versions.","error":"Property 'vds-play' does not exist on type 'HTMLElement'. Did you mean 'play'?"},{"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.","cause":"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).","error":"No matching provider found for source: <URL>"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://www.vidstack.io","github":"https://github.com/vidstack/vidstack","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/vidstack","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","communication"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}