Skip to content
FrameworkStyle

Skins

Packaged player designs that include both UI components and their styles.

A skin wraps the media component and provides the player’s complete interface. It combines a specific set of UI components with the styles that arrange and present them.

Packaged and ejected skins

When you choose a skin you have two options for how you use it: packaged or ejected. It’s usually easiest to start with a packaged skin and later eject its internal components into your project when you need more customization.

Packaged skins cover common visual changes through documented CSS custom properties. Packaged video skins also let you replace the poster. When you need more than that, eject and change the components and styles directly.

Packaged Ejected
Single component Many UI components
Documented CSS custom properties Components and styles you own
Future design updates auto-applied by bumping the version Future design updates manually applied, or intentionally ignored

Packaged skin

<script type="module">
  import '@videojs/html/video/player';
  import '@videojs/html/video/skin';
</script>

<video-player>
  <video-skin>
    <video src="video.mp4"></video>
  </video-skin>
</video-player>

Don’t depend on elements, class names, or undocumented custom properties inside a packaged skin. They may change between releases.

Ejected skin

An ejected skin exposes its UI components and styles as app code that you own. You can add, remove, rearrange, or restyle any part of it.

<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/html@10.0.0-beta.31/cdn/video.js"></script>
<link rel="stylesheet" href="./player.css">

<video-player poster="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.webp">
  <media-container class="media-default-skin media-default-skin--video">
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" playsinline></video>

    <media-poster>
      <img alt="" decoding="async" />
    </media-poster>

    <media-buffering-indicator class="media-buffering-indicator">
      <media-icon name="spinner" class="media-icon"></media-icon>
    </media-buffering-indicator>

    <media-error-dialog>
      <media-dialog-backdrop class="media-overlay media-error-backdrop"></media-dialog-backdrop>
      <media-dialog-popup class="media-error">
      <div class="media-error__dialog media-surface">
        <div class="media-error__content">
          <media-dialog-title class="media-error__title"></media-dialog-title>
          <media-dialog-description class="media-error__description"></media-dialog-description>
        </div>
        <div class="media-error__actions">
          <media-dialog-close class="media-button media-button--primary"></media-dialog-close>
        </div>
      </div>
      </media-dialog-popup>
    </media-error-dialog>

    <media-controls>
      <media-controls-backdrop class="media-overlay"></media-controls-backdrop>
      <media-controls-content class="media-surface media-controls media-controls--root">
      <media-tooltip-group>
        <div class="media-surface media-controls media-controls--primary">
          <div class="media-button-group">
            <media-play-button commandfor="play-tooltip" class="media-button media-button--subtle media-button--icon media-button--play">
              <media-icon name="restart" class="media-icon media-icon--restart"></media-icon>
              <media-icon name="play" class="media-icon media-icon--play"></media-icon>
              <media-icon name="pause" class="media-icon media-icon--pause"></media-icon>
            </media-play-button>
            <media-tooltip id="play-tooltip" side="top" class="media-surface media-tooltip">
              <media-tooltip-label></media-tooltip-label>
              <media-tooltip-shortcut class="media-tooltip__kbd"></media-tooltip-shortcut>
            </media-tooltip>

            <media-mute-button commandfor="video-volume-popover" class="media-button media-button--subtle media-button--icon media-button--mute">
              <media-icon name="volume-off" class="media-icon media-icon--volume-off"></media-icon>
              <media-icon name="volume-low" class="media-icon media-icon--volume-low"></media-icon>
              <media-icon name="volume-high" class="media-icon media-icon--volume-high"></media-icon>
            </media-mute-button>

            <media-popover id="video-volume-popover" open-on-hover delay="200" close-delay="100" side="top" class="media-surface media-popover media-popover--volume">
              <media-volume-slider class="media-slider" orientation="vertical" thumb-alignment="edge">
                <media-slider-track class="media-slider__track">
                  <media-slider-fill class="media-slider__fill"></media-slider-fill>
                </media-slider-track>
                <media-slider-thumb class="media-slider__thumb media-slider__thumb--persistent"></media-slider-thumb>
              </media-volume-slider>
            </media-popover>
          </div>

          <div class="media-time-controls">
            <media-time type="current" class="media-time"></media-time>
            <media-time-slider class="media-slider">
              <media-time-slider-chapters class="media-slider__chapters">
                <template>
                  <div class="media-slider__chapter">
                    <media-slider-track class="media-slider__track media-slider__chapter-track">
                      <media-slider-buffer class="media-slider__buffer"></media-slider-buffer>
                      <media-slider-fill class="media-slider__fill"></media-slider-fill>
                    </media-slider-track>
                  </div>
                </template>
              </media-time-slider-chapters>
              <media-slider-thumb class="media-slider__thumb"></media-slider-thumb>

              <media-slider-preview overflow="visible" class="media-slider__preview">
                <div class="media-surface media-thumbnail media-slider__thumbnail">
                  <media-slider-thumbnail class="media-thumbnail__image"></media-slider-thumbnail>
                  <media-icon name="spinner" class="media-thumbnail__spinner media-icon"></media-icon>
                </div>
                <div class="media-slider__value">
                  <media-time-slider-chapter-title class="media-slider__chapter-title"></media-time-slider-chapter-title>
                  <media-slider-value type="pointer" class="media-time"></media-slider-value>
                </div>
              </media-slider-preview>
            </media-time-slider>
            <media-time toggle type="remaining" class="media-time"></media-time>
          </div>

          <div class="media-button-group">
            <media-captions-button commandfor="captions-tooltip" class="media-button media-button--subtle media-button--icon media-button--captions">
              <media-icon name="captions-off" class="media-icon media-icon--captions-off"></media-icon>
              <media-icon name="captions-on" class="media-icon media-icon--captions-on"></media-icon>
            </media-captions-button>
            <media-tooltip id="captions-tooltip" side="top" class="media-surface media-tooltip">
              <media-tooltip-label></media-tooltip-label>
              <media-tooltip-shortcut class="media-tooltip__kbd"></media-tooltip-shortcut>
            </media-tooltip>

            <button id="settings-trigger" commandfor="settings-menu" aria-labelledby="settings-label" class="media-button media-button--subtle media-button--icon media-button--settings">
              <media-icon name="gear" class="media-icon media-icon--settings"></media-icon>
              <media-text token="menu.settings" id="settings-label" class="media-sr-only">Settings</media-text>
            </button>
            <media-menu id="settings-menu" side="top" align="center" class="media-surface media-popover media-menu media-menu--settings">
              <media-menu-content class="media-menu__content">
                <media-menu-item commandfor="settings-quality-menu" class="media-menu__item media-menu__item--submenu">
                  <media-icon name="switches" class="media-icon"></media-icon>
                  <media-text token="menu.quality">Quality</media-text>
                  <span class="media-menu__hint">
                    <bdi data-part="hint" dir="auto" class="media-menu__hint-label"></bdi>
                    <media-icon name="chevron" class="media-icon media-menu__chevron"></media-icon>
                  </span>
                </media-menu-item>
                <media-menu-item commandfor="settings-audio-menu" class="media-menu__item media-menu__item--submenu">
                  <media-icon name="speech" class="media-icon"></media-icon>
                  <media-text token="menu.audio">Audio</media-text>
                  <span class="media-menu__hint">
                    <bdi data-part="hint" dir="auto" class="media-menu__hint-label"></bdi>
                    <media-icon name="chevron" class="media-icon media-menu__chevron"></media-icon>
                  </span>
                </media-menu-item>
                <media-menu-item commandfor="settings-speed-menu" class="media-menu__item media-menu__item--submenu">
                  <media-icon name="speed" class="media-icon"></media-icon>
                  <media-text token="menu.speed">Speed</media-text>
                  <span class="media-menu__hint">
                    <bdi data-part="hint" dir="auto" class="media-menu__hint-label"></bdi>
                    <media-icon name="chevron" class="media-icon media-menu__chevron"></media-icon>
                  </span>
                </media-menu-item>
                <media-menu-item commandfor="settings-captions-menu" class="media-menu__item media-menu__item--submenu">
                  <media-icon name="captions-off" class="media-icon"></media-icon>
                  <media-text token="menu.captions">Captions</media-text>
                  <span class="media-menu__hint">
                    <bdi data-part="hint" dir="auto" class="media-menu__hint-label"></bdi>
                    <media-icon name="chevron" class="media-icon media-menu__chevron"></media-icon>
                  </span>
                </media-menu-item>
              </media-menu-content>
              <media-menu-content id="settings-quality-menu" class="media-menu__panel">
                <media-menu-item class="media-menu__back">
                  <media-icon name="chevron" class="media-icon media-menu__chevron media-icon--flipped"></media-icon>
                  <media-text token="menu.quality">Quality</media-text>
                </media-menu-item>
                <div class="media-menu__separator"></div>
                <media-quality-radio-group class="media-menu__group">
                  <template>
                    <media-menu-radio-item class="media-menu__item">
                      <span>
                        <bdi data-part="label" dir="auto"></bdi>
                        <sup data-part="tier" class="media-menu__tier"></sup>
                      </span>
                      <span data-part="badge" class="media-badge"></span>
                      <media-menu-item-indicator force-mount class="media-menu__indicator">
                        <media-icon name="check" class="media-icon"></media-icon>
                      </media-menu-item-indicator>
                    </media-menu-radio-item>
                  </template>
                </media-quality-radio-group>
              </media-menu-content>
              <media-menu-content id="settings-audio-menu" class="media-menu__panel">
                <media-menu-item class="media-menu__back">
                  <media-icon name="chevron" class="media-icon media-menu__chevron media-icon--flipped"></media-icon>
                  <media-text token="menu.audio">Audio</media-text>
                </media-menu-item>
                <div class="media-menu__separator"></div>
                <media-audio-track-radio-group class="media-menu__group">
                  <template>
                    <media-menu-radio-item class="media-menu__item">
                      <bdi data-part="label" dir="auto"></bdi>
                      <media-menu-item-indicator force-mount class="media-menu__indicator">
                        <media-icon name="check" class="media-icon"></media-icon>
                      </media-menu-item-indicator>
                    </media-menu-radio-item>
                  </template>
                </media-audio-track-radio-group>
              </media-menu-content>
              <media-menu-content id="settings-speed-menu" class="media-menu__panel">
                <media-menu-item class="media-menu__back">
                  <media-icon name="chevron" class="media-icon media-menu__chevron media-icon--flipped"></media-icon>
                  <media-text token="menu.speed">Speed</media-text>
                </media-menu-item>
                <div class="media-menu__separator"></div>
                <media-playback-rate-radio-group class="media-menu__group">
                  <template>
                    <media-menu-radio-item class="media-menu__item">
                      <bdi data-part="label" dir="auto"></bdi>
                      <media-menu-item-indicator force-mount class="media-menu__indicator">
                        <media-icon name="check" class="media-icon"></media-icon>
                      </media-menu-item-indicator>
                    </media-menu-radio-item>
                  </template>
                </media-playback-rate-radio-group>
              </media-menu-content>
              <media-menu-content id="settings-captions-menu" class="media-menu__panel">
                <media-menu-item class="media-menu__back">
                  <media-icon name="chevron" class="media-icon media-menu__chevron media-icon--flipped"></media-icon>
                  <media-text token="menu.captions">Captions</media-text>
                </media-menu-item>
                <div class="media-menu__separator"></div>
                <media-captions-radio-group class="media-menu__group">
                  <template>
                    <media-menu-radio-item class="media-menu__item">
                      <bdi data-part="label" dir="auto"></bdi>
                      <media-menu-item-indicator force-mount class="media-menu__indicator">
                        <media-icon name="check" class="media-icon"></media-icon>
                      </media-menu-item-indicator>
                    </media-menu-radio-item>
                  </template>
                </media-captions-radio-group>
              </media-menu-content>
            </media-menu>
            <media-tooltip id="settings-tooltip" trigger="settings-trigger" side="top" class="media-surface media-tooltip">
              <media-text token="menu.settings">Settings</media-text>
            </media-tooltip>
          </div>
        </div>

        <div class="media-surface media-controls media-controls--secondary">
          <div class="media-button-group">
            <media-cast-button commandfor="cast-tooltip" class="media-button media-button--subtle media-button--icon media-button--cast">
              <media-icon name="cast-enter" class="media-icon media-icon--cast-enter"></media-icon>
              <media-icon name="cast-exit" class="media-icon media-icon--cast-exit"></media-icon>
            </media-cast-button>
            <media-tooltip id="cast-tooltip" side="top" class="media-surface media-tooltip">
              <media-tooltip-label></media-tooltip-label>
              <media-tooltip-shortcut class="media-tooltip__kbd"></media-tooltip-shortcut>
            </media-tooltip>

            <media-airplay-button commandfor="airplay-tooltip" class="media-button media-button--subtle media-button--icon media-button--airplay">
              <media-icon name="airplay-enter" class="media-icon media-icon--airplay-enter"></media-icon>
              <media-icon name="airplay-exit" class="media-icon media-icon--airplay-exit"></media-icon>
            </media-airplay-button>
            <media-tooltip id="airplay-tooltip" side="top" class="media-surface media-tooltip">
              <media-tooltip-label></media-tooltip-label>
              <media-tooltip-shortcut class="media-tooltip__kbd"></media-tooltip-shortcut>
            </media-tooltip>

            <media-pip-button commandfor="pip-tooltip" class="media-button media-button--subtle media-button--icon media-button--pip">
              <media-icon name="pip-enter" class="media-icon media-icon--pip-enter"></media-icon>
              <media-icon name="pip-exit" class="media-icon media-icon--pip-exit"></media-icon>
            </media-pip-button>
            <media-tooltip id="pip-tooltip" side="top" class="media-surface media-tooltip">
              <media-tooltip-label></media-tooltip-label>
              <media-tooltip-shortcut class="media-tooltip__kbd"></media-tooltip-shortcut>
            </media-tooltip>

            <media-fullscreen-button commandfor="fullscreen-tooltip" class="media-button media-button--subtle media-button--icon media-button--fullscreen">
              <media-icon name="fullscreen-enter" class="media-icon media-icon--fullscreen-enter"></media-icon>
              <media-icon name="fullscreen-exit" class="media-icon media-icon--fullscreen-exit"></media-icon>
            </media-fullscreen-button>
            <media-tooltip id="fullscreen-tooltip" side="top" class="media-surface media-tooltip">
              <media-tooltip-label></media-tooltip-label>
              <media-tooltip-shortcut class="media-tooltip__kbd"></media-tooltip-shortcut>
            </media-tooltip>
          </div>
        </div>
      </media-tooltip-group>
      </media-controls-content>
    </media-controls>

    <!-- Hotkeys -->
    <media-hotkey keys="Space" action="togglePaused"></media-hotkey>
    <media-hotkey keys="k" action="togglePaused"></media-hotkey>
    <media-hotkey keys="m" action="toggleMuted"></media-hotkey>
    <media-hotkey keys="f" action="toggleFullscreen"></media-hotkey>
    <media-hotkey keys="c" action="toggleSubtitles"></media-hotkey>
    <media-hotkey keys="i" action="togglePictureInPicture"></media-hotkey>
    <media-hotkey keys="ArrowRight" action="seekStep" value="5"></media-hotkey>
    <media-hotkey keys="ArrowLeft" action="seekStep" value="-5"></media-hotkey>
    <media-hotkey keys="l" action="seekStep" value="10"></media-hotkey>
    <media-hotkey keys="j" action="seekStep" value="-10"></media-hotkey>
    <media-hotkey keys="ArrowUp" action="volumeStep" value="0.05"></media-hotkey>
    <media-hotkey keys="ArrowDown" action="volumeStep" value="-0.05"></media-hotkey>
    <media-hotkey keys="0-9" action="seekToPercent"></media-hotkey>
    <media-hotkey keys="Home" action="seekToPercent" value="0"></media-hotkey>
    <media-hotkey keys="End" action="seekToPercent" value="100"></media-hotkey>
    <media-hotkey keys=">" action="speedUp"></media-hotkey>
    <media-hotkey keys="<" action="speedDown"></media-hotkey>

    <!-- Gestures -->
    <media-gesture type="tap" action="togglePaused" pointer="mouse" region="center"></media-gesture>
    <media-gesture type="tap" action="toggleControls" pointer="touch"></media-gesture>
    <media-gesture type="doubletap" action="seekStep" value="-10" region="left"></media-gesture>
    <media-gesture type="doubletap" action="toggleFullscreen" region="center"></media-gesture>
    <media-gesture type="doubletap" action="seekStep" value="10" region="right"></media-gesture>

    <!-- Input Indicators -->
    <media-status-announcer class="media-sr-only"></media-status-announcer>
    <div class="media-input-indicator-overlay">
      <media-volume-indicator hidden class="media-surface media-volume-indicator">
        <media-volume-indicator-fill class="media-volume-indicator__content">
          <media-icon name="volume-high" class="media-icon media-icon--volume-high"></media-icon>
          <media-icon name="volume-low" class="media-icon media-icon--volume-low"></media-icon>
          <media-icon name="volume-off" class="media-icon media-icon--volume-off"></media-icon>
          <media-volume-indicator-value class="media-volume-indicator__value"></media-volume-indicator-value>
        </media-volume-indicator-fill>
      </media-volume-indicator>
      <media-status-indicator
        hidden
        actions="toggleSubtitles toggleFullscreen togglePictureInPicture"
        class="media-surface media-status-indicator media-status-indicator--state"
      >
        <div class="media-status-indicator__content">
          <media-icon name="captions-on" class="media-icon media-icon--captions-on"></media-icon>
          <media-icon name="captions-off" class="media-icon media-icon--captions-off"></media-icon>
          <media-icon name="fullscreen-enter" class="media-icon media-icon--fullscreen-enter"></media-icon>
          <media-icon name="fullscreen-exit" class="media-icon media-icon--fullscreen-exit"></media-icon>
          <media-icon name="pip-enter" class="media-icon media-icon--pip-enter"></media-icon>
          <media-icon name="pip-exit" class="media-icon media-icon--pip-exit"></media-icon>
          <media-status-indicator-value class="media-status-indicator__value"></media-status-indicator-value>
        </div>
      </media-status-indicator>
      <media-seek-indicator hidden class="media-seek-indicator">
        <media-icon name="chevron" class="media-icon media-icon--seek"></media-icon>
        <media-seek-indicator-value class="media-seek-indicator__value"></media-seek-indicator-value>
      </media-seek-indicator>
      <media-status-indicator hidden actions="togglePaused" class="media-status-indicator media-status-indicator--playback">
        <media-icon name="play" class="media-icon media-icon--play"></media-icon>
        <media-icon name="pause" class="media-icon media-icon--pause"></media-icon>
      </media-status-indicator>
    </div>
  </media-container>
</video-player>

Skins, features, and presets

Each skin is built with specific features in mind. For example, a video skin renders fullscreen and picture-in-picture controls. An audio skin doesn’t.

You’ll find a preconfigured player, its typed hook, a skin, and the matching feature bundle exported from the same path. We call these paths presets.

ImportDescriptionDetails
@videojs/html/videoGeneral-purpose video player preset with full playback controls.
@videojs/html/audioAudio-only player preset with playback and volume controls.
@videojs/html/backgroundAmbient background video preset with no user controls.
@videojs/html/live-audioLive audio player preset — same features as audio with a skin that omits duration / current-time displays.
@videojs/html/live-videoLive video player preset — same features as video with a skin that omits duration / current-time displays.

Styling

Packaged skins use vanilla CSS. Their documented CSS custom properties cover common visual changes.

The skin registration entry point imports its styles automatically.

To use Tailwind or change the underlying CSS, eject the skin and edit its styles in your app.

Shared limitations

  • Skin spacing and icons use a fixed 16px base by default. Vanilla CSS font sizes use the same base, while Tailwind font sizes use rem units and assume a 16px root font size.
  • The default font stack includes Inter, but we do not load the webfont for you. If Inter is unavailable, the skin uses system fonts.

Ejected vanilla CSS

  • We use a BEM classname structure and every component classname is scoped with a media- prefix.

Ejected Tailwind

  • Ejected skins establish their own spacing scale but otherwise assume the default configuration. A future CLI eject command will support custom class prefixes. For now, edit the ejected skin to use your prefix.
  • Ejected skins currently support Tailwind 4.3.x.