1. Getting Started
  2. Installation

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

    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.

  2. Select JS Library

    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

    Embed video content into documents via the native video element.

  4. Select Styling

    The Community Skin is our production-ready UI when you're looking for something pre-designed and ready out of the box. See the Skins docs for previews, features, and customization options.

  5. Install NPM Package

    Install vidstack and dependencies via NPM.

    terminal
            npm i vidstack
    
          
  6. Register Elements

    Register the custom media elements and base styles.

    js
            import 'vidstack/styles/defaults.css'
    import 'vidstack/styles/community-skin/video.css'
    
    import { defineCustomElements } from 'vidstack/elements';
    
    defineCustomElements();
    
          

    You can also register specific elements like so:

    js
            // 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
            <media-player
      title="Sprite Fight"
      src="https://stream.mux.com/VZtzUzGRv02OhRnZCxcNg49OilvolTqdnFLEqBsTwaxU/low.mp4"
      poster="https://image.mux.com/VZtzUzGRv02OhRnZCxcNg49OilvolTqdnFLEqBsTwaxU/thumbnail.webp?time=268&width=980"
      thumbnails="https://media-files.vidstack.io/sprite-fight/thumbnails.vtt"
      aspect-ratio="16/9"
      crossorigin
    >
      <media-outlet>
        <media-poster
          alt="Girl walks into sprite gnomes around her friend on a campfire in danger!"
        ></media-poster>
       <track
          src="https://media-files.vidstack.io/sprite-fight/subs/english.vtt"
          label="English"
          srclang="en-US"
          kind="subtitles"
          default
        />
        <track
          src="https://media-files.vidstack.io/sprite-fight/chapters.vtt"
          srclang="en-US"
          kind="chapters"
          default
        />
      </media-outlet>
      <media-community-skin></media-community-skin>
    </media-player>
    
          
  8. Add Global Types

    Add global Vidstack types if you're using TypeScript.

    tsconfig.json
            {
      "compilerOptions": {
        "types": ["vidstack/globals"]
      }
    }
    
          

Customizing Skins

See the Skins docs for further skin customization options.

Media Icons

This step is optional. Media Icons is a collection of icons we've designed at Vidstack to help with building audio and video player user interfaces. If you plan on building your components up yourself (i.e., not using a skin or any defaults), then you can follow the instructions below to start using our icons.

First, install the media-icons package:

        npm i media-icons

      

Next, import icons:

ts
        import 'vidstack/icons';

      

Finally, use them like so:

html
        <media-icon type="chromecast" />

      

👉 Preview the entire collection in our media icons catalog.