Skip to content

GuideGetting Started

Browser support

Browsers and rendering environments supported by Video.js 10, and how the packaged skins reach them

Supported browsers, the versions of each that Video.js supports, and the older versions the Compat skin also reaches
BrowserVersionsCompat skin
Chrome111 and later99 and later
Edge111 and later99 and later
Firefox121 and later97 and later
Safari16.4 and later15.4 and later
Safari on iOS16.4 and later15.4 and later

These versions account for 92.5% of global web usage according to caniuse-lite 1.0.30001815, and the Compat versions account for 94.4%. These figures update when we update that data.

We test in and fix bugs for the main versions. Each of those minimums comes from a feature with no fallback: :has() sets Firefox, color-mix() and oklch() set Chrome and Edge (Chrome 111, Firefox 113, Safari 16.2), and the JavaScript sets Safari, because it uses ES2022 syntax and adoptedStyleSheets. Newer JavaScript APIs are feature-detected.

The Compat skin also reaches the older versions in the last column. It leaves out backdrop blur, anchor-positioned menu highlights, and squircle corners, and its stylesheets fall back to plain colors where color-mix() and oklch() are missing. Below the main versions, it keeps its narrow layout and default size, because container queries and media query ranges are missing, and the time slider preview stays hidden on keyboard focus. Every build checks its stylesheets against these older versions, and our browser tests run at the main versions.

The Scaffold skin, a starting point for your own design, reaches the same older versions.

The HTML player’s JavaScript needs Firefox 101 and Safari 16.4, so with HTML the Compat skin reaches Chrome and Edge 99, Firefox 101, and Safari 16.4.

The older versions apply to the packaged skins. Tailwind skins follow Tailwind’s own browser support, and registry skins in plain CSS need @scope unless you flatten it. If your build lowers CSS for its own targets, include these older versions in them, or it may rewrite the fallbacks.

CSS requirements

The packaged skins are generated CSS, and the build lowers them for the main versions above. It flattens CSS nesting, adds vendor prefixes such as -webkit-backdrop-filter, and writes each skin’s scope as a :where() selector, which adds no specificity, rather than @scope.

Skins you add as source through the Shadcn registry keep @scope, which reads more clearly in files you edit. Their plain CSS versions need Chrome and Edge 118, Firefox 146, and Safari and iOS 17.4 unless you flatten @scope in your build; the Tailwind versions style elements with utility classes and follow the versions above.

Newer color functions get a fallback, and the original declaration moves inside @supports, so browsers that have the function still use it:

  • light-dark() uses its light color. The audio skins render their light theme, and the video skins keep the light hairline border.
  • contrast-color() uses each theme’s default text color on primary buttons and the inherited text color elsewhere. The fallback cannot read a custom accent, so set --media-accent-text-color whenever you set --media-accent-color; see Customize skins.
  • Relative colors that keep their origin’s channels, which build the scrims behind the controls, become color-mix(). Subtle shadows derived from currentColor have no equivalent and are left out.

Tooltips, menus, and popovers use the Popover API where it exists (Chrome 114, Firefox 125, Safari 17). In older supported versions they stay inside the player instead of the top layer: the skins hide them while closed and position them against the player while open, so on the video skins a menu taller than the player is cut off.

The table reads the first fully supporting version of each feature from caniuse-lite when the docs build, and feature names link to caniuse.com. Required features have no fallback. Degrades features lose one visual detail. Has a fallback features keep working another way: anchor positioning falls back to positions computed in JavaScript, :dir() sits beside [dir="rtl"] selectors, and the packaged skins flatten @scope into :where() selectors.

First browser version that fully supports each CSS feature the packaged skins use, with the share of global web usage on supporting browsers. Feature names link to their caniuse.com support data. "Not supported" means the browser has no full support. Paired browsers share a column and show two values only when they differ.
FeatureChrome and EdgeFirefoxSafari and iOSGlobal support
@scope
Has a fallback. Packaged skins use :where() selectors instead; registry CSS skins need it.
11814617.491.7%
@layer
Required. No component styling.
999715.496.0%
:has()
Required. Menu and slider focus states are lost.
Compat loses only the time slider preview on keyboard focus.
10512115.494.8%
@container
Required. Controls do not adapt to player width.
Compat keeps its narrow layout, without the center controls or the duration.
1061101694.8%
Media query range syntax
Required. Large-screen sizing is lost.
1046316.494.8%
:dir()
Has a fallback. Right-to-left layout follows the dir attribute instead.
1201716.492.5%
Relative color syntax
Degrades. Control scrims fall back to color-mix(), and subtle shadows are lost.
1311331887.0%
scrollbar-color and scrollbar-width
Degrades. Menus show default scrollbars.
1216426.287.0%
backdrop-filter
Degrades. Surfaces lose their blur.
Compat does not use it.
76 / 17103996.4%
Anchor positioning
Has a fallback. Popups are positioned by JavaScript.
Not supportedNot supported270.0%

Below the main versions, only the Compat and Scaffold skins are supported. Without :has(), @container, @layer, color-mix(), or oklch(), the Default and Neutral skins lose focus states, layout, or colors.

Build the skin CSS yourself

Packaged HTML skins inline their CSS into JavaScript, so add the skin source to your project first. The added skin.css can pass through your CSS pipeline. CDN bundles inline their CSS too; to recompile it, move to a self-hosted build and use the skin source instead of the prebuilt CDN skin.

Lightning CSS, which Vite uses to minify CSS, rewrites light-dark() and :dir() for every browser when its targets include older ones, not only for those older browsers. Its light-dark() output depends on a color-scheme declaration the skins do not make, so the skin colors break. The skins keep light-dark() inside @supports checks, which Lightning CSS 1.32 and earlier leave alone but 1.33 and later rewrite anyway. The skins already handle both features, so exclude them:

import { Features } from 'lightningcss';
import { defineConfig } from 'vite';

export default defineConfig({
  css: {
    lightningcss: { exclude: Features.LightDark | Features.DirSelector },
  },
});

Flatten @scope in registry skins

Registry skins in plain CSS keep @scope, and Lightning CSS passes it through unchanged. To reach browsers without @scope, add a PostCSS plugin that rewrites each block into descendant selectors prefixed with :where(root), which adds no specificity. Vite, Next.js, and most bundlers pick it up from postcss.config.mjs and run it before Lightning CSS:

npm install --save-dev postcss postcss-selector-parser
import selectorParser from 'postcss-selector-parser';

/** Rewrite `@scope (<root>) { … }` into descendant selectors that older browsers understand. */
function flattenScope() {
  const rewrite = (selector, root) =>
    selectorParser((selectors) => {
      selectors.each((sel) => {
        let referencesRoot = false;

        sel.walk((node) => {
          if (node.type === 'nesting' || (node.type === 'pseudo' && node.value === ':scope')) {
            node.replaceWith(selectorParser.string({ value: `:where(${root})` }));
            referencesRoot = true;
          }
        });

        if (!referencesRoot) {
          sel.prepend(selectorParser.combinator({ value: ' ' }));
          sel.prepend(selectorParser.string({ value: `:where(${root})` }));
        }
      });
    }).processSync(selector);

  return {
    postcssPlugin: 'flatten-scope',
    OnceExit(css) {
      const scopes = [];
      css.walkAtRules('scope', (atRule) => scopes.push(atRule));

      // Innermost first, so a nested scope is flattened before its parent prefixes it.
      for (const atRule of scopes.reverse()) {
        const match = /^\(\s*(.+?)\s*\)\s*$/.exec(atRule.params);
        if (!match || /\)\s*to\s*\(/.test(atRule.params)) continue;

        atRule.walkRules((rule) => {
          rule.selectors = rule.selectors.map((selector) => rewrite(selector.trim(), match[1]));
        });
        atRule.replaceWith(atRule.nodes);
      }
    },
  };
}
flattenScope.postcss = true;

export default { plugins: [flattenScope()] };

Flattening trades scope proximity for source order, the same way the packaged skins do. Keep the Lightning CSS exclude setting above so the colors still work.

Rendering contexts

WebViews

A WebView is a browser engine embedded inside a native app. WebViews on iOS (WKWebView) and Android (Android WebView) can behave differently from the full browser; autoplay policies, fullscreen APIs, and hardware acceleration can vary.

Video.js 10 targets standard browser environments. If you embed a player inside a native app, test it on each platform and WebView version you support.

Progressive Web Apps

Installed Progressive Web Apps (PWAs) use the browser engine, but their standalone display mode and platform policies can affect fullscreen, media sessions, and other browser integration. Test playback both in a browser tab and in the installed app.

Smart TVs and set-top boxes

TV platforms run embedded browsers with limited standards support. Video.js 10’s core is not tied to any specific platform, which makes future TV adapters possible, but TV is not a supported target today.

Server-side rendering

Video.js components render valid markup on the server. Interactivity — state management, media playback, and event handling — requires the browser and kicks in after hydration.

Guides