Getting Started

Installation

This section will get you up and running with the library. You'll find specific instructions below depending on the type of installation method (NPM or CDN), library (HTML, React, etc.), and provider (Audio, Video, HLS, etc.) you opt to use.

1. # Select Install Method

   Select Install Method NPM

   NPMCDN

   Locally installing the package via NPM is best when you're integrating the library with build tools such as Parcel, Rollup, Vite, or Webpack. We ship both an un-optimized development bundle that includes logs, and a production bundle that is specially minified to get the bundle size as small as possible. Thanks to Node package exports your bundler will automatically load the correct type based on the Node process environment (NODE_ENV).

   Why use NPM?

2. # Select JS Library

   Select JS Library HTML

   HTMLReact

   The HTML option refers to our Web Components library. Our custom elements can be used anywhere with the simple drop of an import or CDN link as they're natively supported by browsers. This option is best when writing plain HTML or using a JS library such as Angular. Native web components have excellent support in most libraries.

3. # Select Media Provider

   Select Media Provider Video

   AudioVideoHLS

   Embed video content into documents via the native video element.

4. # Select Styling

   Select Styling Preference Defaults

   NoneHeadlessDefaultsCommunity SkinPlyr Skin

   The default styles are best when you want to build your own player, but you don't want to design each component from zero. Our default styles have been built to be extremely easy to customize! Other options include no styles at all (none option), unstyled components (headless option), or having a complete design out of the box (skins option).

5. # Install NPM Package

   Install vidstack and dependencies via NPM.

   terminal

   Copied

   Copy

           npm i vidstack
   
         

6. # Register Elements

   Register the custom media elements and base styles.

   js

   Copied

   Copy

           import 'vidstack/styles/defaults.css';
   
   import { defineCustomElements } from 'vidstack/elements';
   
   defineCustomElements();
   
         

   Individual styles can be imported like so:

   js

   Copied

   Copy

           import 'vidstack/styles/base.css';
   import 'vidstack/styles/ui/buttons.css';
   import 'vidstack/styles/ui/captions.css';
   import 'vidstack/styles/ui/tooltips.css';
   import 'vidstack/styles/ui/live.css';
   import 'vidstack/styles/ui/sliders.css';
   
   import { defineCustomElements } from 'vidstack/elements';
   
   defineCustomElements();
   
         

   You can also register specific elements like so:

   js

   Copied

   Copy

           // the `.js` extension is required.
   import 'vidstack/define/media-player.js';
   
         

7. # Add Player Markup

   Add the following player HTML boilerplate to get started.

   html

   Copied

   Copy

           <!-- remove `controls` attribute if you're designing a custom UI -->
   <media-player
     src="https://media-files.vidstack.io/720p.mp4"
     poster="https://media-files.vidstack.io/poster.png"
     controls
   >
     <media-outlet></media-outlet>
   </media-player>
   
         

8. # Add Global Types

   Add global Vidstack types if you're TypeScript.

   tsconfig.json

   Copied

   Copy

           {
     "compilerOptions": {
       "types": ["vidstack/globals"]
     }
   }