1. Core Concepts
  2. Autoplay

Core Concepts


In this section, we'll look at how to autoplay media and detect when it inevitably fails.


A perfect starting point on understanding how browsers handle autoplay is this article by Chrome Developers. In short, the best chance you have for autoplay working on a site where a user is visiting for the first time, or irregularly is by muting the media. Try to encourage the user to either play or unmute the media themselves to avoid a poor experience.


We manually handle autoplay so we can detect when it fails. Therefore, ensure you set autoplay on the media component instead of the underlying provider like so:


The autoplay attribute on the <audio> or <video> element will take priority over the preload attribute. Never set this attribute because it will break the loading process.


The following media attributes are available for styling based on the current autoplay state:

        vds-media[autoplay][started] {
  /** autoplay has successfully started. */

vds-media[autoplay-error] {
  /** autoplay has failed. */


You can use the CSS selectors above to style child elements as desired based on the autoplay state. This can be useful for showing fallback controls in the event it fails.


The following events are available for detecting whether autoplay succeeds or fails: