Looking for the old docs? Go here

Getting Started

CDN Installation Guide

Instructions to get your player up and running using the JSDelivr CDN.

Web Components
A layout refers to the arrangement and presentation of various player components. The CSS and Tailwind CSS options below are if you want to style components from scratch and build your own layout. The Default Theme option is if you want to build your own layout on top of our component styles. Finally, the Default and Plyr layouts are our production-ready templates to get you up and running quickly.

Default Theme
Default Layout
Plyr Layout
Tailwind CSS

Ensure the following browser support table is suitable for your application. We’ve built the library for the modern web; thus, we try to avoid bloated polyfills and outdated environments as much as possible. At the moment, we only support browsers that fully implement the Custom Elements V1 spec.


We support at minimum ~94.18% of users tracked on caniuse.


The following import will register all custom media elements (e.g., <media-player>) and import global TypeScript types:


You can append .dev to any CDN URL to load the development version:


You can also pin the CDN package version by appending @x.x.x like so:


You can also construct the player using JavaScript. The target argument can be a query selector or HTMLElement. If the target is a <audio>, <video>, or <iframe> element it will be progressively enhanced. See the JavaScript installation page for more information.


See the Poster component for how to display an image while video content is loading, or until the user hits play. If this is not included, the first frame of the video will be used instead.

The playsinline property will indicate that video content should be played inline (on mobile only), rather than launching the video in fullscreen mode on play. In addition, setting this property will also ensure custom player UI is displayed on iPhone when playing inline (hidden in fullscreen mode as native controls are forcefully displayed by the browser).

Important to note, we normalize the playing inline behaviour across all mobile browsers. If you do not set playsinline, the video will launch in fullscreen on play in all mobile browsers, not just iOS Safari where the attribute is accepted.


By default, the player and all components will destroy themselves if they’re removed from the DOM and not reattached after an animation frame tick (i.e., requestAnimationFrame). If you or your router are moving player components around the DOM for unknown amounts of time, consider keeping the player and all children alive, and manually destroying all component instances.


The keep-alive attribute can be set on any media element, not just the player. Important to note that it’s forwarded to all children. Any root component with keep-alive must be destroyed by calling the destroy() method on the element instance as shown above.

You should be all set up by this point. We recommend exploring our 👉 examples to learn how to start building and customizing your player. You can also use the examples to make sure you’ve set everything up correctly.

From here you’re free to explore the library.

Lastly, remember you’re not alone. You can reach out for help or to talk with other developers using Vidstack: