videojs · sampotts · Mar 10, 2026
diff --git a/packages/html/src/define/base.css b/packages/html/src/define/base.css
@@ -1,5 +1,6 @@
 video-player {
-  display: contents;
+  display: block;
+  width: 100%;
 }
 
 video-player video,

diff --git a/packages/html/src/define/skin-mixin.ts b/packages/html/src/define/skin-mixin.ts
@@ -1,24 +1,15 @@
 import type { ReactiveElement } from '@videojs/element';
 import type { Constructor } from '@videojs/utils/types';
-import styles from './base.css?inline';
-
-const STYLES_ID = '__media-styles';
-
-function ensureStyles(): void {
-  if (document.getElementById(STYLES_ID)) return;
-  const style = document.createElement('style');
-  style.id = STYLES_ID;
-  style.textContent = styles;
-  document.head.appendChild(style);
-}
 
 /**
  * Mixin for skin elements that renders the template from a static
  * `getTemplateHTML` method into a shadow root. Native `<slot>` elements
  * handle light DOM projection automatically.
  *
- * When `static styles` is set, the stylesheet is adopted into the
- * shadow root via `adoptedStyleSheets`.
+ * Consumers should include `@videojs/html/base.css` in light DOM for
+ * provider layout defaults and native caption bridge styles. When
+ * `static styles` is set, the stylesheet is adopted into the shadow
+ * root via `adoptedStyleSheets`.
  */
 export function SkinMixin<Base extends Constructor<ReactiveElement>>(
   BaseClass: Base
@@ -30,8 +21,6 @@ export function SkinMixin<Base extends Constructor<ReactiveElement>>(
     constructor(...args: any[]) {
       super(...args);
 
-      ensureStyles();
-
       if (!this.shadowRoot) {
         const ctor = this.constructor as typeof SkinElement & { getTemplateHTML?: () => string };
         this.attachShadow(ctor.shadowRootOptions);

diff --git a/packages/sandbox/app/shared/html/stylesheets.ts b/packages/sandbox/app/shared/html/stylesheets.ts
@@ -1,5 +1,7 @@
 import type { Skin } from '../../types';
 
+const baseStylesheet = new URL('@videojs/html/base.css', import.meta.url).href;
+
 const videoStylesheets: Record<Skin, string> = {
   default: new URL('@videojs/html/video/skin.css', import.meta.url).href,
   minimal: new URL('@videojs/html/video/minimal-skin.css', import.meta.url).href,
@@ -22,9 +24,11 @@ function loadStylesheet(url: string) {
 }
 
 export function loadVideoStylesheets(skin: Skin) {
+  loadStylesheet(baseStylesheet);
   loadStylesheet(videoStylesheets[skin]);
 }
 
 export function loadAudioStylesheets(skin: Skin) {
+  loadStylesheet(baseStylesheet);
   loadStylesheet(audioStylesheets[skin]);
 }
diff --git a/packages/sandbox/templates/html-hls-video/main.ts b/packages/sandbox/templates/html-hls-video/main.ts
@@ -1,4 +1,5 @@
 import '@app/styles.css';
+import '@videojs/html/base.css';
 import '@videojs/html/video/player';
 import '@videojs/html/media/hls-video';
 import '@videojs/html/video/skin';
@@ -21,8 +22,8 @@ function render() {
   loadVideoStylesheets(currentSkin);
 
   document.getElementById('root')!.innerHTML = html`
-    <video-player>
-      <${tag} class="w-full aspect-video max-w-4xl mx-auto">
+    <video-player class="w-full aspect-video max-w-4xl mx-auto">
+      <${tag}>
         <hls-video slot="media" src="${SOURCES[currentSource].url}"></hls-video>
       </${tag}>
     </video-player>

diff --git a/packages/sandbox/templates/html-simple-hls-video/main.ts b/packages/sandbox/templates/html-simple-hls-video/main.ts
@@ -1,4 +1,5 @@
 import '@app/styles.css';
+import '@videojs/html/base.css';
 import '@videojs/html/video/player';
 import '@videojs/html/media/simple-hls-video';
 import '@videojs/html/video/skin';
@@ -21,8 +22,8 @@ function render() {
   loadVideoStylesheets(currentSkin);
 
   document.getElementById('root')!.innerHTML = html`
-    <video-player>
-      <${tag} class="w-full aspect-video max-w-4xl mx-auto">
+    <video-player class="w-full aspect-video max-w-4xl mx-auto">
+      <${tag}>
         <simple-hls-video slot="media" src="${SOURCES[currentSource].url}"></simple-hls-video>
       </${tag}>
     </video-player>

diff --git a/packages/sandbox/templates/html-video-tailwind/main.ts b/packages/sandbox/templates/html-video-tailwind/main.ts
@@ -1,4 +1,5 @@
 import '@app/styles.css';
+import '@videojs/html/base.css';
 import '@videojs/html/video/player';
 import '@videojs/html/video/skin.tailwind';
 import '@videojs/html/video/minimal-skin.tailwind';
@@ -20,8 +21,8 @@ function render() {
   const tag = TAILWIND_SKIN_TAGS[currentSkin].video;
 
   document.getElementById('root')!.innerHTML = html`
-    <video-player>
-      <${tag} class="w-full aspect-video max-w-4xl mx-auto">
+    <video-player class="w-full aspect-video max-w-4xl mx-auto">
+      <${tag}>
         <video slot="media" src="${SOURCES[currentSource].url}"></video>
       </${tag}>
     </video-player>

diff --git a/packages/sandbox/templates/html-video/main.ts b/packages/sandbox/templates/html-video/main.ts
@@ -1,4 +1,5 @@
 import '@app/styles.css';
+import '@videojs/html/base.css';
 import '@videojs/html/video/player';
 import '@videojs/html/video/skin';
 import '@videojs/html/video/minimal-skin';
@@ -20,8 +21,8 @@ function render() {
   loadVideoStylesheets(currentSkin);
 
   document.getElementById('root')!.innerHTML = html`
-    <video-player>
-      <${tag} class="w-full aspect-video max-w-4xl mx-auto">
+    <video-player class="w-full aspect-video max-w-4xl mx-auto">
+      <${tag}>
         <video slot="media" src="${SOURCES[currentSource].url}"></video>
       </${tag}>
     </video-player>

diff --git a/packages/sandbox/templates/simple-hls-html/main.ts b/packages/sandbox/templates/simple-hls-html/main.ts
@@ -14,6 +14,7 @@ import '@videojs/html/media/container';
 import '@videojs/html/media/simple-hls-video';
 import '@videojs/html/ui/play-button';
 import '@videojs/html/ui/mute-button';
+import '@videojs/html/base.css';
 import { pauseIcon, playIcon, restartIcon, volumeHighIcon, volumeOffIcon } from '@videojs/icons/html';
 
 const html = String.raw;

diff --git a/site/src/components/installation/HTMLCdnCodeBlock.tsx b/site/src/components/installation/HTMLCdnCodeBlock.tsx
@@ -18,12 +18,14 @@ function generateCdnCode(useCase: UseCase, skin: Skin): string {
   import '${CDN_BASE}/background/player.js';
   import '${CDN_BASE}/background/skin.js';
 </script>
+<link rel="stylesheet" href="${CDN_BASE}/base.css" />
 <link rel="stylesheet" href="${CDN_BASE}/background/skin.css" />`;
   }
 
   const name = getCdnFileName(useCase, skin);
 
   return `<script type="module" src="${CDN_BASE}/${name}.js"></script>
+<link rel="stylesheet" href="${CDN_BASE}/base.css" />
 <link rel="stylesheet" href="${CDN_BASE}/${name}.css" />`;
 }
 

diff --git a/site/src/components/installation/HTMLUsageCodeBlock.tsx b/site/src/components/installation/HTMLUsageCodeBlock.tsx
@@ -122,7 +122,8 @@ import '@videojs/html/background/video';${mediaImport}`;
   const { group, skinFile } = getSkinImportParts(skin);
   const mediaSubpath = getMediaImportSubpath(renderer);
   const mediaImport = mediaSubpath ? `\nimport '@videojs/html/media/${mediaSubpath}';` : '';
-  return `import '@videojs/html/${group}/player';
+  return `import '@videojs/html/base.css';
+import '@videojs/html/${group}/player';
 import '@videojs/html/${group}/${skinFile}';
 import '@videojs/html/${group}/${skinFile}.css';${mediaImport}`;
 }