@videojs/html 10.0.0-rc.1 → 10.0.0-rc.3

package/docs/guides/thumbnails.md

@@ -0,0 +1,183 @@
+# Show timeline thumbnail previews
+
+Preview frames along the timeline while the user scrubs, powered by a storyboard track.
+
+Show preview frames along the timeline while the user scrubs, like YouTube’s seek previews.
+
+> **Tip: Using Mux?**
+>
+> With [`<mux-video>`](../reference/components/mux-video.md), the storyboard track is wired up for you — skip adding the track and go straight to the slider thumbnail. For other services, generate the storyboard on their platform and add the track yourself.
+
+> **Note**
+>
+> Using a pre-built [skin](./skins.md)? It already includes the controls shown here. You may still need the media or player setup in this guide. The component examples are for building your own player UI from individual [components](./ui-components.md).
+
+## Recommended approach
+
+Add a `kind="metadata"` track labeled `thumbnails` whose cues reference storyboard images, then put a slider thumbnail inside the [`<media-time-slider>`](../reference/components/time-slider.md). Scrubbing shows the frame under the pointer. The slider thumbnail reads the pointer time from the slider, so you never pass `time`; it otherwise accepts the same attributes as the standalone [`<media-thumbnail>`](../reference/components/thumbnail.md).
+
+`<media-slider-thumbnail>` draws its own image unless you supply an `<img>` child; set `crossorigin`, `loading`, or `fetchpriority` on the element itself, or on the image you supply. Inside a packaged skin, an `<img slot="thumbnail">` replaces the image the skin carries, so those attributes go on it:
+
+```html
+<video-player>
+  <video-skin>
+    <video src="video.mp4" crossorigin="anonymous">
+      <track kind="metadata" label="thumbnails" src="storyboard.vtt" default />
+    </video>
+    <img slot="thumbnail" alt="" loading="lazy" fetchpriority="low" />
+  </video-skin>
+</video-player>
+```
+
+**index.html**
+
+```html
+<video-player class="video-player">
+  <media-container>
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop crossorigin="anonymous">
+      <track kind="metadata" label="thumbnails" src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.vtt" default />
+    </video>
+    <media-time-slider class="media-time-slider">
+      <media-slider-track class="media-slider-track">
+        <media-slider-fill class="media-slider-fill"></media-slider-fill>
+      </media-slider-track>
+      <media-slider-thumbnail class="media-slider-thumbnail"></media-slider-thumbnail>
+    </media-time-slider>
+  </media-container>
+</video-player>
+```
+
+**index.css**
+
+```css
+.video-player {
+  position: relative;
+  display: block;
+}
+
+.video-player video {
+  width: 100%;
+}
+
+.media-time-slider {
+  position: absolute;
+  right: 10px;
+  bottom: 6px;
+  left: 10px;
+  display: flex;
+  align-items: center;
+  height: 20px;
+  cursor: pointer;
+}
+
+.media-slider-track {
+  position: absolute;
+  right: 0;
+  left: 0;
+  height: 4px;
+  background: rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  transition: height 150ms ease;
+}
+
+.media-time-slider[data-interactive] .media-slider-track {
+  height: 6px;
+}
+
+.media-slider-fill {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: var(--media-slider-fill);
+  height: 100%;
+  background: white;
+  border-radius: 9999px;
+}
+
+/* Reveal the preview over the pointer while it is on the slider. */
+.media-slider-thumbnail {
+  position: absolute;
+  bottom: 100%;
+  left: var(--media-slider-pointer);
+  max-width: 160px;
+  margin-bottom: 8px;
+  pointer-events: none;
+  border-radius: 4px;
+  opacity: 0;
+  transform: translateX(-50%);
+  transition: opacity 150ms ease;
+}
+
+.media-time-slider[data-pointing] .media-slider-thumbnail {
+  opacity: 1;
+}
+
+.media-slider-thumbnail[data-hidden] {
+  display: none;
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/video/player';
+import '@videojs/html/ui/container';
+import '@videojs/html/ui/time-slider';
+import '@videojs/html/ui/slider-track';
+import '@videojs/html/ui/slider-fill';
+import '@videojs/html/ui/slider-thumbnail';
+```
+
+## How it works
+
+- Previews come from a storyboard: a `kind="metadata"` text track labeled `thumbnails` whose WebVTT cues map time ranges to image URLs (optionally with sprite coordinates). The [text track feature](../reference/api/feature-text-tracks.md) exposes these as `thumbnailCues` and `thumbnailTrackSrc`.
+- The slider thumbnail renders the storyboard frame for the slider’s pointer position. While the pointer is over the slider, the slider sets `data-pointing` and the `--media-slider-pointer` CSS variable; the example’s CSS uses them to reveal the preview and position it over the pointer.
+- To render a storyboard frame outside the slider — a fixed preview for a chapter list, for example — use the standalone [`<media-thumbnail>`](../reference/components/thumbnail.md) element with an explicit `time`.
+
+Each cue’s text is an image URL. An optional `#xywh=x,y,w,h` fragment crops one frame out of a sprite sheet:
+
+**storyboard.vtt**
+
+```txt
+WEBVTT
+
+00:00:00.000 --> 00:00:05.000
+storyboard.jpg#xywh=0,0,256,160
+
+00:00:05.000 --> 00:00:10.000
+storyboard.jpg#xywh=256,0,256,160
+```
+
+## Availability and constraints
+
+- Thumbnails require a storyboard asset generated alongside the media; the player doesn’t extract frames from the video itself.
+- Cross-origin storyboards need CORS headers, and `crossorigin` on the media element for the track to load.
+- Cues load asynchronously. The track appears before its cues are parsed, so previews fill in when the track finishes loading.
+- Storyboard images download on demand; oversized sprite sheets hurt seek-preview responsiveness more than they help quality.
+
+## Troubleshooting
+
+### Thumbnails don’t appear while scrubbing
+
+Confirm the storyboard track is `kind="metadata"` with `label="thumbnails"` and has the `default` attribute — the browser leaves a non-default track disabled and never loads its cues. Then confirm the VTT loads (network panel) and cross-origin assets have CORS headers with `crossorigin` set on the media element.
+
+### Thumbnails are blurry or slow
+
+Regenerate the storyboard with a larger frame size, or split giant sprite sheets into smaller images.
+
+## Related pages
+
+### Components
+
+- [media-thumbnail](../reference/components/thumbnail.md): Time-based thumbnail preview component for timeline scrubbing and hover previews
+- [media-slider](../reference/components/slider.md): A composable slider component with track, fill, thumb, preview, and value parts
+- [media-time-slider](../reference/components/time-slider.md): A slider component for seeking through media playback time
+
+### API
+
+- [Text tracks](../reference/api/feature-text-tracks.md): Subtitles, captions, and chapter track state for the player store
+
+### Guides
+
+- [Add a poster and loading placeholder](./poster.md): Set the image shown before playback, then add a lightweight placeholder while it loads
+- [Show captions and subtitles](./captions.md): Show captions and subtitles, and let users turn them on and pick a language.

package/docs/guides/typescript.md

@@ -0,0 +1,41 @@
+# TypeScript
+
+TypeScript version and module resolution requirements for Video.js packages
+
+Video.js packages require **TypeScript 5.0 or newer**. TypeScript must also follow the import paths that each package publishes.
+
+## TypeScript version
+
+Video.js type files use syntax introduced in TypeScript 5.0. Older versions cannot read that syntax. The `skipLibCheck` option does not help because TypeScript must read a type file before it can skip checking it.
+
+## Module resolution
+
+Video.js packages define their supported import paths using [package exports](./bundlers.md). Most web applications should use the following configuration. It makes TypeScript follow the same package rules as the bundler that builds the application:
+
+**tsconfig.json**
+
+```json
+{
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "bundler"
+  }
+}
+```
+
+If Node.js runs files emitted directly by TypeScript, use `node16` for both `module` and `moduleResolution`, or use `nodenext` for both.
+
+Do not use the older `node` setting, now called `node10`. It does not understand package exports and can report valid Video.js imports or types as missing.
+
+## Errors from other dependencies
+
+The older `node` setting allowed applications to import almost any file inside a dependency. Modern settings allow only the paths that dependency publishes. Changing the setting can therefore reveal an existing import into another package’s private files.
+
+If the error names a package outside `@videojs/*`, update that dependency or use one of its supported import paths. A TypeScript `paths` override can be a temporary bridge when no supported replacement exists. Do not switch back to the older resolver because that also breaks Video.js type resolution.
+
+## Related pages
+
+### Guides
+
+- [Installation](./installation.md): Install Video.js packages and build an accessible, customizable video player with composable controls
+- [Bundlers](./bundlers.md): Bundler requirements for Video.js package exports, CSS, and wrapper libraries

package/docs/guides/ui-components.md

@@ -0,0 +1,75 @@
+# UI components
+
+How Video.js UI components use focused elements, data attributes for state, and compound composition.
+
+UI components are controls like buttons, sliders, and time displays.
+
+Visible UI components render at most one HTML element, taking inspiration from projects like [shadcn/ui](https://ui.shadcn.com/) and [Base UI](https://base-ui.com/). This approach gives you control over styling and behavior while handling the complex interactions for you. State-only components render no markup, and controls can skip rendering when their feature is unavailable.
+
+Individual controls provide interaction, accessible names, and state. You add their visible text or icons and CSS. Sliders also need the child elements and styles shown on their reference pages.
+
+## Where to put your components
+
+Each `@videojs/html/ui/*` import registers exactly one custom element. Compound components such as controls, sliders, menus, and dialogs need an import for the root and for every part you render, so a `<media-controls-content>` inside `<media-controls>` needs both `ui/controls` and `ui/controls-content`. Without its import, a part stays a plain element and never receives its state attributes. Each reference page lists the imports for its anatomy, and the skin entry points register everything their layout uses.
+
+UI components can go anywhere inside a [`<video-player>`](../reference/components/player.md).
+
+However, you should consider placing your components in `<media-container>`. Components in `<media-container>` will go fullscreen with the player, respond to user activity, and more.
+
+- [Read more about `<media-container>`](../reference/components/player-container.md)
+
+## Styling and customization
+
+For components you add yourself, select them by their custom element name. Use the documented state `data-*` attributes and CSS custom properties to style them.
+
+### Add icons
+
+Import `@videojs/html/icons/element` once in your `app.ts` to register `<media-icon>`. Choose an icon with `name`. Set `family="minimal"` to use the Minimal skin’s icon designs. You can also use your own text or SVG.
+
+```ts
+import '@videojs/html/icons/element';
+```
+
+```html
+<media-play-button class="my-play-button">
+  <media-icon class="play-icon" name="play"></media-icon>
+  <media-icon class="pause-icon" name="pause"></media-icon>
+</media-play-button>
+```
+
+### Style components with state
+
+Components add `data-*` attributes to describe their current state. For example, a play button adds `data-paused` while the media is paused. Use those attributes in CSS:
+
+```css
+.my-play-button .pause-icon {
+  display: none;
+}
+
+.my-play-button:defined:not([data-paused]) .play-icon {
+  display: none;
+}
+
+.my-play-button:defined:not([data-paused]) .pause-icon {
+  display: inline-flex;
+}
+```
+
+The browser matches `:defined` after it loads the custom element. This keeps the play icon visible while JavaScript loads.
+
+Each component’s reference page documents its full set of data attributes.
+
+Some components also expose **CSS custom properties** for continuous values like fill percentage and pointer position. Sliders, for example, set `--media-slider-fill` and `--media-slider-pointer`. See individual component reference pages for specifics.
+
+## Compound components
+
+Complex interactions are split into composable parts. A parent manages shared state while children consume it. Each visible part owns at most one element.
+
+```html
+<media-volume-slider orientation="vertical">
+  <media-slider-track>
+    <media-slider-fill></media-slider-fill>
+  </media-slider-track>
+  <media-slider-thumb></media-slider-thumb>
+</media-volume-slider>
+```

package/docs/guides/user-preferences.md

@@ -0,0 +1,132 @@
+# Remember user preferences
+
+Persist volume, caption, and quality preferences across sessions by subscribing to player state.
+
+The player doesn’t persist preferences itself today. Player state gives you everything needed to wire persistence to the storage you choose — local storage, your backend, or per-profile settings.
+
+## Recommended approach
+
+Subscribe to the state you want to remember, write it to storage when it changes, and restore it once the store attaches to the media.
+
+```html
+<video-player>
+  <media-container>
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" playsinline></video>
+  </media-container>
+</video-player>
+<script type="module">
+  import '@videojs/html/video/player';
+  import { selectVolume } from '@videojs/html';
+
+  const STORAGE_KEY = 'player:volume';
+  const player = document.querySelector('video-player');
+  const store = player.store;
+
+  // Local storage can be unavailable (private modes), so guard reads and writes.
+  function readSaved() {
+    try {
+      return JSON.parse(localStorage.getItem(STORAGE_KEY) ?? 'null');
+    } catch {
+      return null;
+    }
+  }
+
+  function save(prefs) {
+    try {
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(prefs));
+    } catch {
+      // Storage unavailable; skip persistence.
+    }
+  }
+
+  // Restore once the store attaches to the media; actions throw before that.
+  const saved = readSaved();
+  if (saved) {
+    const restore = () => {
+      if (!store.target) return false;
+      const v = selectVolume(store.state);
+      v?.setVolume(saved.volume);
+      // setVolume above zero unmutes, so mute again if that's the saved preference.
+      // At volume zero the player already counts as muted, and toggling would unmute.
+      if (v && saved.muted && saved.volume > 0) v.toggleMuted();
+      return true;
+    };
+    if (!restore()) {
+      const unsubscribe = store.subscribe(() => {
+        if (restore()) unsubscribe();
+      });
+    }
+  }
+
+  // Save on change. subscribe() fires on any state change, so diff what you care about.
+  let last = saved ?? {};
+  store.subscribe(() => {
+    const v = selectVolume(store.state);
+    if (!v || (v.volume === last.volume && v.muted === last.muted)) return;
+    last = { volume: v.volume, muted: v.muted };
+    save(last);
+  });
+</script>
+```
+
+## How it works
+
+- Player state is the single source of truth: it already reflects every change, whatever caused it — your UI, keyboard shortcuts, native controls, or scripts.
+- `store.subscribe(callback)` fires on any state change. Notifications are batched per microtask, so rapid changes (a volume drag) produce one callback per tick, which keeps storage writes cheap. There is no per-key subscription on the store: read the state and diff the slice you care about.
+- Feature selectors exported by `@videojs/html` (`selectVolume`, `selectTextTrack`, `selectQuality`, and the rest) read a feature’s slice from any store, returning `undefined` when the feature isn’t present.
+- Restore through the feature actions (`setVolume`, `toggleMuted`, `selectSubtitlesTrack`, `selectVideoRendition`) rather than poking the media element, so state and UI stay consistent.
+- Actions need an attached media target: calling one before the store attaches throws. Check `store.target` and defer the restore until it is set, as the examples do.
+
+## Availability and constraints
+
+- Nothing persists by default: volume resets to the media element’s value, captions to the track markup, quality to automatic, on every load.
+- `setVolume` clamps to 0–1 and unmutes when setting a value above zero; restore volume first, then toggle `muted` back on when the saved preference is muted, as the examples do. Skip the toggle when the saved volume is zero: the player treats volume zero as muted, so toggling would unmute and raise the volume. Don’t compare against store state right after calling an action: notifications batch per microtask, so that state is still stale.
+- Restore track and quality selections after the media exposes them: track and rendition lists arrive when the media loads, not at player creation. Subscribe and apply when the saved entry appears in the list.
+- Programmatic volume control is unavailable on some platforms (after attach, iOS Safari reports `volumeAvailability: 'unsupported'`); volume persistence quietly does nothing there.
+- Local storage is per-origin and can be unavailable (private modes, embedded contexts); guard reads and writes accordingly.
+
+## Common variations
+
+### Persist caption preference
+
+Save the showing track’s `language` (not its generated id, which can change between sources), or `'off'` when the user turns captions off. Restoring is two phases: while the media loads, assert the saved preference whenever the track modes drift from it, because browsers can auto-enable a track of their own during loading. Once the media can play (`canPlay`), treat every change as the user’s choice and save it. A restore that re-runs forever would keep overriding the user; one that runs only once can get overridden by the browser.
+
+Apply the same pattern with `selectTextTrack(store.state)` inside `store.subscribe`: until `canPlay` is true, re-apply the saved preference by passing the matching track’s `id` (or `'off'`) to `selectSubtitlesTrack` whenever the modes drift; afterward, save the showing track’s `language`, or `'off'` when none is showing, on every change.
+
+### Persist to your backend
+
+Swap `localStorage` for an API call; the subscription pattern is identical. Debounce writes beyond the built-in microtask batching if your storage is remote.
+
+## Troubleshooting
+
+### The saved volume doesn’t apply
+
+Restore runs before the store attaches, or the platform doesn’t allow programmatic volume (check `volumeAvailability`). Apply after `store.target` is set, as in the examples.
+
+### The saved caption track doesn’t select
+
+The track list wasn’t loaded yet when you restored, or you saved a generated track id instead of a stable property like `language`. React to `textTrackList` changes and match on language.
+
+### Storage writes fire constantly while dragging the volume slider
+
+Notifications batch per microtask, but a drag still produces many ticks. Debounce the write if the churn matters for your storage target.
+
+## Related pages
+
+### Components
+
+- [media-volume-slider](../reference/components/volume-slider.md): A slider component for controlling media playback volume
+- [media-captions-radio-group](../reference/components/captions-radio-group.md): A menu radio group for selecting caption and subtitle tracks
+- [media-quality-radio-group](../reference/components/quality-radio-group.md): A menu radio group for selecting video quality
+
+### API
+
+- [PlayerController](../reference/api/player-controller.md): Reactive controller for accessing player store state in HTML custom elements
+- [StoreController](../reference/api/store-controller.md): Reactive controller for subscribing to store state in HTML custom elements
+- [Volume](../reference/api/feature-volume.md): Volume level and mute state for the player store
+- [Text tracks](../reference/api/feature-text-tracks.md): Subtitles, captions, and chapter track state for the player store
+
+### Guides
+
+- [Show captions and subtitles](./captions.md): Show captions and subtitles, and let users turn them on and pick a language.
+- [Add a quality selector](./quality.md): Read available renditions, let the engine adapt automatically, and offer manual quality selection.

package/docs/guides/v10-roadmap.md

@@ -0,0 +1,92 @@
+# v10 Roadmap
+
+Timeline and milestones for Video.js v10 rebuild and the future of v8
+
+Video.js v10 is a complete rebuild from the ground up, designed to be more modular, framework-flexible, and aligned with modern web development practices.
+
+## Current versions
+
+### Version 8
+
+- Maintained with bug fixes and critical security patches only
+- No new features will be planned
+- Community contributions still welcome
+- Documentation available at [legacy.videojs.org](https://legacy.videojs.org)
+
+### Version 9
+
+- Reserved only for urgent API-breaking changes that cannot be avoided
+
+## March 2026: v10 Beta Release
+
+Wider testing release to the community.
+
+### Core feature parity target
+
+- Basic control set (play, pause, seek, volume, fullscreen)
+- Adaptive streaming support via existing community engines
+- No plugin migrations yet, without plugin author contribution
+
+### What to expect
+
+- Close to stable, but API changes are still possible
+- Intended for experimental adoption in real-world projects
+- Developers encouraged to follow the [installation guide](./installation.md), try it out, and report issues
+
+## September 2026: v10 Release Candidate
+
+Feature-complete release ahead of GA.
+
+### What to expect
+
+- Close to stable. Remaining API changes are driven by feedback on the release candidate
+- Intended for adoption in real-world projects
+- Migration guides and reference documentation ready for review
+
+## Fall 2026: v10 GA Release
+
+**Stable release** of Video.js v10
+
+### Feature targets
+
+- Core feature parity with v8 in terms of fundamentals
+- Feature parity with Media Chrome, Vidstack, Plyr, and Mux Player
+- Community encouraged to begin full reintegration projects, following the migration guides for [Video.js 8](./migrate-from-video-js-8.md), [Mux Player](./migrate-from-mux-player.md), [Plyr](./migrate-from-plyr.md), and [Media Chrome](./migrate-from-media-chrome.md)
+- Plugin ecosystem migration begins in earnest
+
+### Engine development focus
+
+- Lightweight adaptive streaming
+- MoQ (Media over QUIC) support
+
+## Late-2026: Feature parity with v8 Contrib
+
+**Extended feature parity** with Video.js “contrib” plugins:
+
+- Ads integration
+- Analytics support
+- Further community plugin migration dependent on contributions
+
+## End-of-life plan for Video.js v8
+
+### Mid-2026
+
+- v8/v9 moved to “video.js-legacy” repository and package
+- Documentation preserved at [legacy.videojs.org](https://legacy.videojs.org)
+- Hosted CDN copies will remain available
+
+### 2027 and beyond
+
+- Security patches only
+- Community contributions de-prioritized
+
+---
+
+**Want to contribute?** Check out the [v10 repository on GitHub](https://github.com/videojs/v10) to get involved in the rebuild
+
+## Related pages
+
+### Guides
+
+- [Why Video.js?](./why-videojs.md): The open-source video player for React and HTML. Lightweight, accessible components built for performance and streaming.
+- [Installation](./installation.md): Install Video.js packages and build an accessible, customizable video player with composable controls

package/docs/guides/vue.md

@@ -0,0 +1,156 @@
+# Vue
+
+Add Video.js to a Vue or Nuxt app
+
+Follow the [installation guide](./installation.md) first. Keep its `@videojs/html` imports and player markup in your Vue component, then apply the Vue-specific configuration below.
+
+## Configure custom element tags
+
+If Vue warns that it cannot resolve a Video.js tag, the compiler is treating that tag as a Vue component. Use Vue’s [`isCustomElement`](https://vuejs.org/guide/extras/web-components.html#skipping-component-resolution) option to identify the exact Video.js tags in your templates.
+
+For a Vue app built with Vite:
+
+**vite.config.ts**
+
+```ts
+import vue from '@vitejs/plugin-vue';
+import { defineConfig } from 'vite';
+
+const videoJsElements = new Set(['video-player', 'video-skin', 'mux-video']);
+
+export default defineConfig({
+  plugins: [
+    vue({
+      template: {
+        compilerOptions: {
+          isCustomElement: (tag) => videoJsElements.has(tag),
+        },
+      },
+    }),
+  ],
+});
+```
+
+For Nuxt:
+
+**nuxt.config.ts**
+
+```ts
+const videoJsElements = new Set(['video-player', 'video-skin', 'mux-video']);
+
+export default defineNuxtConfig({
+  vue: {
+    compilerOptions: {
+      isCustomElement: (tag) => videoJsElements.has(tag),
+    },
+  },
+});
+```
+
+List only the tags that appear in your templates. Avoid broad rules such as allowing every hyphenated tag or every tag with one prefix: Video.js uses several tag families, and broad rules can also hide misspelled Vue components.
+
+## Read player state
+
+If your Vue component needs to react to player state or call a player action, wait until Vue has mounted `<video-player>`. The React API’s `usePlayer` hook is not part of `@videojs/html`, so use a template ref and subscribe to the element’s store:
+
+```vue
+<script setup lang="ts">
+import type { VideoPlayerElement } from '@videojs/html/video';
+import { onMounted, onUnmounted, ref } from 'vue';
+
+const player = ref<VideoPlayerElement | null>(null);
+const paused = ref(true);
+let unsubscribe = () => {};
+
+onMounted(() => {
+  const store = player.value!.store;
+  const sync = () => (paused.value = store.paused);
+  sync();
+  unsubscribe = store.subscribe(sync);
+});
+
+onUnmounted(() => unsubscribe());
+</script>
+
+<template>
+  <video-player ref="player"><!-- skin and media --></video-player>
+  <p>{{ paused ? 'Paused' : 'Playing' }}</p>
+</template>
+```
+
+Use the store for player state and actions. Unsubscribe in `onUnmounted`.
+
+When you need the native event itself, attach a listener to the `<video>`, `<audio>`, or media custom element:
+
+```vue
+<script setup lang="ts">
+function handleLoadedMetadata(event: Event) {
+  const media = event.currentTarget as HTMLVideoElement;
+  console.log(`Duration: ${media.duration} seconds`);
+}
+</script>
+
+<template>
+  <video @loadedmetadata="handleLoadedMetadata"><!-- sources and tracks --></video>
+</template>
+```
+
+## Style Vue components
+
+If you want to hide an element until the browser loads it, use `:defined` in your component’s scoped styles:
+
+```vue
+<style scoped>
+video-skin:not(:defined) {
+  visibility: hidden;
+}
+</style>
+```
+
+Scoped styles cannot reach controls inside a packaged skin. Use its CSS custom properties, or [add the skin source to your project](./customize-skins.md#style-skin-source) to change its markup and CSS.
+
+## Pass objects as properties
+
+If you need to pass structured data, such as a Mux source, an HTML attribute will not work because attributes contain text. Vue’s [`.prop` modifier](https://vuejs.org/api/built-in-directives.html#v-bind) assigns the value to the element’s JavaScript property:
+
+The Mux media ships as its own adapter package, so add it to the HTML installation used by this example:
+
+```bash
+pnpm add @videojs/html @videojs/mux-video
+```
+
+```vue
+<script setup lang="ts">
+import '@videojs/html/video/player';
+import '@videojs/html/video/skin';
+import '@videojs/html/media/mux-video';
+
+const source = {
+  playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
+  playback: { maxResolution: '1080p' },
+} as const;
+</script>
+
+<template>
+  <video-player>
+    <video-skin>
+      <mux-video :source.prop="source"></mux-video>
+    </video-skin>
+  </video-player>
+</template>
+```
+
+Use `.prop` explicitly. An ordinary binding or render-function prop can become an attribute if Vue runs before the custom element finishes loading. Video.js preserves explicitly assigned properties during that upgrade.
+
+## Use Nuxt
+
+If you use server rendering, keep the element imports from the installation guide static. Nuxt renders the custom-element markup on the server, and the browser upgrades it when the page loads.
+
+If you intentionally keep registration client-only, import the elements from a `.client.ts` plugin and wait for `customElements.whenDefined('video-player')` before reading its store or calling its methods. For custom tag or event types, follow Vue’s [TypeScript guidance for non-Vue custom elements](https://vuejs.org/guide/extras/web-components.html#non-vue-web-components-and-typescript).
+
+## Related pages
+
+### Guides
+
+- [Installation](./installation-vue.md): Install Video.js with Vue in Vite, Astro, or Nuxt and build a player with HTML custom elements
+- [Customize skins](./customize-skins.md): Style a packaged Video.js skin or add its source to change controls, layout, styles, and interactions