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.

# Player Installation

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).

   Bundle vs. CDN

   So you can best decide what install method is best for you, we'll quickly look at some good reasons to locally bundle instead of using a CDN.

   • It provides the greatest control over the library. If you're looking to build your own player elements or modify certain behaviour, then this is the path of least resistance.

   • It provides the optimal development experience working with the library because your IDE can provide you with type/value validation and documentation. We also ship a helpful integration for VSCode so you can get autocomplete suggestions for our custom elements when writing HTML.

   • It leads to less duplication of code as dependencies of this library (e.g, Lit) will be bundled only once. If you're using a CDN, any dependencies that are used both in your application and the player library will be loaded twice.

   • Reduces the final bundle size as your bundler can perform tree-shaking through static analysis to eliminate dead-code (i.e., unused imports). We've marked side-effect files in the library to improve this process further.

   • Reduces the number of HTTP requests and round-trips required to load the player. Ultimately, this speeds up the time it takes for the player to load because your bundler can optimize the loading and evaluating time of JavaScript by grouping code into chunks.

   • You can easily take advantage of dynamic imports to determine when the browser loads the library. You don't want the loading of player-related code to block your users from interacting with your application.

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 HLS

   AudioVideoHLS

   Embed video content into documents via the native video element. This provider also enables streaming video using the HTTP Live Streaming (HLS) protocol. HLS isn't widely supported yet, but we use the popular hls.js library to ensure it works anywhere Media Source Extensions (MSE) are supported, which accounts for ~96.42% of users tracked on caniuse.

4. # Install NPM Package

   Install vidstack and dependencies via NPM.

   terminal

   Copied

   Copy

           npm i hls.js vidstack
   
         

5. # Register Elements

   Register the custom media elements and base styles.

   js

   Copied

   Copy

           import 'vidstack/styles/base.css';
   // the following styles are optional - remove to go headless.
   import 'vidstack/styles/ui/buttons.css';
   import 'vidstack/styles/ui/sliders.css';
   
   import { defineCustomElements } from 'vidstack/elements';
   
   defineCustomElements();
   
         

   You can register specific elements like so:

   js

   Copied

   Copy

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

6. # 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/hls/index.m3u8"
     poster="https://media-files.vidstack.io/poster.png"
     controls
   >
     <media-outlet></media-outlet>
   </media-player>
   
         

7. # Add Global Types

   Add global Vidstack types if you're using TypeScript.

   tsconfig.json

   Copied

   Copy

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