Getting Started
Web Component Installation Guide
Instructions to get your player installed and on-screen using Web Components.
1. Select Framework
Section titled 1. Select Framework2. Select Bundler
Section titled 2. Select Bundler3. Select Provider
Section titled 3. Select Provider4. Select Styling
Section titled 4. Select Styling5. Check Support
Section titled 5. Check SupportEnsure 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.
6. Install Packages
Section titled 6. Install Packages7. Setup Bundler
Section titled 7. Setup BundlerYou can skip this step since you're not using a bundler.
8. Import Library
Section titled 8. Import LibraryThe following imports will include the required CSS styles and variables:
The following imports will register all custom media elements (e.g., <media-player>) and import global TypeScript types:
9. Player Markup
Section titled 9. Player Markup10. Poster (Optional)
Section titled 10. Poster (Optional)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.
11. Playsinline (Optional)
Section titled 11. Playsinline (Optional)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.
12. Visual Studio (Optional)
Section titled 12. Visual Studio (Optional)This step is optional. VS Code (VSC) provides support for extending the known HTML entities through VSC Custom Data. Once set up, it enables autocomplete suggestions for custom player elements and on-hover information such as documentation and type data.
- Create the VSC settings file at the root of your project directory:
- Add the custom HTML data file path to
html.customDatainside the newly created settings file:
13. Media Icons (Optional)
Section titled 13. Media Icons (Optional)You can skip this step since you're using the Default Layout.
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. You can preview the entire collection in our media icons catalog.
- First, install the
media-iconspackage:
- Import them like so:
- Finally, you can start using them like so:
14. Keep Alive (Optional)
Section titled 14. Keep Alive (Optional)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.
15. Examples
Section titled 15. ExamplesYou 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.
16. Next Steps
Section titled 16. Next StepsFrom here you’re free to explore the library.
- Scan over the remaining docs pages to get a good overview of how the library works.
- Explore the API and Components references.
- Check out the Default Layout or Plyr Layout pages if you’re using them.
- See the Tailwind Plugin if you’re using Tailwind CSS and building your own layout.
Lastly, remember you’re not alone. You can reach out for help or to talk with other developers using Vidstack: