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.

Player Installation

  1. Select Install Method

    Using a CDN like JSDelivr is the simplest and fastest way to start using the player library. We provide a CDN bundle that includes all package dependencies, and it's specially minified to get the bundle size as small as possible.

    Why use a CDN?

    So you can best decide what install method is best for you, we'll quickly look at some good reasons to use a CDN. Refer to the NPM option to find good counter reasons using the select menu above.

    • It's simple. There's no build step or anything to install. Add a few script tags, and you're ready to start creating a player, making this an ideal option for development, playground, and low-code environments (e.g., WordPress and Shopify).

    • If you aren't importing from the library or building any custom elements, there may be no point in checking it into Git. It's one less dependency to track, version control, and load in your Git repository. Refer to the NPM install option to find good reasons why you should still bundle it locally (if possible).

    • You'll get much faster load times because JSDelivr uses a multi-CDN architecture and has more than 750 points of presence (PoPs). All other users of our library who are also using the CDN will pull the code closer to all PoPs while keeping the cache warm every time they make a request.

    • It'll reduce the load and stress on your server. If you're already at your server limit computationally or financially, it may be best to delegate loading of some resources to an externally managed CDN.

  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. Register Elements

    Add the following link and script tags to register the custom media elements.

    html
            <!DOCTYPE html>
    <html>
      <head>
        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vidstack/styles/base.min.css" />
        <!-- the following styles are optional - remove to go headless -->
        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vidstack/styles/ui/buttons.min.css" />
        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vidstack/styles/ui/sliders.min.css" />
        <script type="module" src="https://cdn.jsdelivr.net/npm/vidstack/dist/cdn/prod.js"></script>
      </head>
      <!-- ... -->
    </html>
    
          
  5. Add Player Markup

    Add the following player HTML boilerplate to get started.

    html
            <!-- 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>
    
          
  6. Add Global Types

    Add global Vidstack types if you're using TypeScript.

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