1. Getting Started
  2. Styling

Getting Started


In this section, we'll cover the basics on how you can easily put together a custom UI with Vidstack Player.


All UI elements in the library are headless, meaning they contain no styling out of the box. It's up to you how they look, as they only provide some core functionality. For example, the <vds-play-button> component will dispatch play and pause requests when pressed, but other than that, it is completely blank.

The player exposes media state as attributes and CSS variables on the <vds-media> element (aka <Media> component):

  style="--vds-current-time: 500; --vds-duration: 1000; ..."
  <!-- ... -->


You can use the presence and absence of these attributes to style children of the <vds-media> element with CSS. Here's a quick example where we add a controls container and hide it based on some media state:

        .media-controls {
  display: flex;
  position: absolute;
  bottom: 0;
  left: 0;
  width: 100%;
  min-height: 48px;
  opacity: 1;
  transition: opacity ease 300ms;
  /* Position above media provider. */
  z-index: 1;

/* Avoid double controls on iOS when in fullscreen. */
vds-media[hide-ui] .media-controls {
  opacity: 0;
  visibility: hidden;

 * Hide controls if either user is idle, or media is not
 * ready for playback.
vds-media[user-idle] .media-controls,
vds-media:not([can-play]) .media-controls {
  opacity: 0;


[attr] selects elements based on the presence or value of an attribute, and the :not() pseudo-class represents elements that do not match a list of selectors. We can combine these to create powerful selectors based on the media state being exposed and updated on the <vds-media> element.

Media Attributes

Here's a reference table that displays all the media attributes that are set on the <vds-media> element.

autoplayAutoplay has successfully started.
autoplay-errorAutoplay has failed to start.
can-loadMedia can begin loading.
can-playMedia is ready to be played.
can-fullscreenMedia fullscreen is available.
endedPlayback has reached the end.
errorIssue with media loading/playback.
fullscreenMedia is in fullscreen mode.
user-idleUser is not active during playback.
loopMedia is set to loop back to start on end.
mutedMedia is muted.
pausedPlayback is in a paused state.
playingPlayback has started or resumed.
playsinlineMedia should play inline by default (iOS Safari).
seekingMedia or user is seeking to new playback position.
startedMedia playback has started.
waitingMedia is waiting for more data (i.e., buffering).

Media CSS Variables

Here's a reference table that displays all the media CSS variables that are set on the <vds-media> element.

--vds-buffered-amountThe amount of media that has buffered in seconds (0 -> duration).
--vds-current-timeThe current playback time in seconds (0 -> duration).
--vds-durationThe total length of media in seconds.
--vds-seekable-amountThe amount of media that is seekable in seconds (0 -> duration).