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

package/docs/guides/cdn.md

@@ -0,0 +1,102 @@
+# CDN
+
+Understand the browser-ready bundles, stylesheets, and URL layout published by the Video.js CDN
+
+Start with the [CDN Installation Guide](./installation-cdn.md) to load Video.js and add a working player. This guide documents the browser-ready files the CDN serves and the layout rules behind their URLs.
+
+## CDN URLs
+
+Every file the CDN serves follows one URL pattern:
+
+```plaintext
+https://cdn.jsdelivr.net/npm/@videojs/cdn@<version>/<file>
+```
+
+> **Caution: Pin all your CDN URLs to the same version.**
+>
+> Bundles share content-hashed chunks that change between releases. A tag like `@latest` re-resolves over time, so two files might come from different releases and load duplicate modules that no longer share state.
+
+## Player bundles
+
+Each installation [preset](./presets.md) ships its bundles at the package root: one per skin choice, plus a player-only bundle. For the video preset:
+
+| File | Registers |
+| --- | --- |
+| `video.js` | `<video-player>`, `<video-skin>`, and the UI elements the skin composes |
+| `video-minimal.js` | `<video-player>`, `<video-minimal-skin>`, and the UI elements the minimal skin composes |
+| `video-player.js` | `<video-player>` alone, for markup without a packaged skin |
+
+The other presets follow the same pattern. Background video is the exception: one bundle, `background.js`, registers the player, the skin, and the `<background-video>` media element.
+
+A skin bundle registers every UI element its skin is built from. Any element the skin does not compose is its own bundle under `ui/`.
+
+## UI element bundles
+
+Each [UI element](./ui-components.md) is its own bundle under `ui/`, for markup that a skin bundle does not already cover: a player-only bundle, [skin source](./customize-skins.md#style-skin-source) that adds a component the packaged skin lacks, or a [dialog](../reference/components/dialog.md) your page opens beside a packaged skin.
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/video-player.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/ui/play-button.js"></script>
+```
+
+Each path mirrors its npm subpath: `ui/play-button.js` registers the element that `@videojs/html/ui/play-button` does. Compound components list one bundle per part in their reference page’s Import section, and all of the bundles share chunks with the player.
+
+## Media bundles
+
+The default presets play through the browser’s own `<video>` and `<audio>`. Every other [media element](./media-sources.md) is its own bundle under `media/`, loaded beside the player bundle:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/media/hlsjs-video.js"></script>
+```
+
+Each path mirrors its npm subpath. Elements with more than one playback engine keep the extra flavors in a directory named for the element, such as `media/mux-video/spf.js`. Load one flavor per page: every flavor claims the same tag name, and the first registration wins.
+
+## Extension bundles
+
+Each [extension](./architecture.md) is its own bundle under `extensions/`, loaded beside the player and media bundles:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/media/mux-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/extensions/mux-data.js"></script>
+```
+
+As with media, each path mirrors its npm subpath: `extensions/mux-data.js` registers the element that `@videojs/html/extensions/mux-data` does.
+
+## Locales
+
+English ships inside the skin bundles. Each other locale is a bundle under `locales/` that registers its translations on import. Load it before the player script to avoid a flash of English:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/locales/es.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/video.js"></script>
+```
+
+One bundle exists per locale pack, plus bare-language aliases such as `pt`. For custom strings, see [Internationalize the player](./internationalization.md).
+
+## Stylesheets
+
+The skin bundles inline their CSS, so no `<link>` is required to render. The separate `.css` files do the jobs a bundle cannot:
+
+- `global.css` holds the light-DOM rules. Link it in `<head>` and the player reserves its space before the elements upgrade. The background preset uses `background.css` instead.
+- The skin sheets, such as `video.css` beside `video.js`, style declaratively rendered skins.
+- `shadow.css` holds the shadow-root integration rules that hand-written shadow skins build on.
+
+[Self-host the player](./self-hosting.md) shows both in use.
+
+## Development bundles
+
+Every JavaScript entry has a `.dev.js` sibling, such as `video.dev.js`, built with development warnings on. Swap the suffix while debugging; swap it back to ship.
+
+## Shared chunks
+
+Everything else at the root, including content-hashed files such as `adapter-<hash>.js`, is a shared chunk the entries import by relative path. Entries share these chunks, so loading several bundles stays cheap. Chunk names change every release: never link a chunk directly, and never copy a lone entry file. To mirror the CDN, copy the whole package directory and keep its layout; [Self-host the player](./self-hosting.md) covers it.
+
+## Related pages
+
+### Guides
+
+- [CDN Installation Guide](./installation-cdn.md): Load Video.js from jsDelivr and build an HTML video player without installing Video.js packages
+- [Self-host the player](./self-hosting.md): Serve the Video.js HTML player from your own origin for offline, air-gapped, or restricted-network deployments
+- [Internationalize the player](./internationalization.md): Translate player labels and announcements: shipped locale packs, custom translations, runtime switching, and server rendering.

package/docs/guides/content-security-policy.md

@@ -0,0 +1,37 @@
+# Content Security Policy
+
+Allow the media, images, workers, and styles a Video.js player needs when your page enforces a Content Security Policy
+
+Content Security Policy (CSP) limits which resources a page can load. Video.js uses the URLs you configure for media, posters, thumbnails, and captions. Some HLS renderers also create blob URLs or web workers, so your policy must allow those resources too.
+
+## Allow player resources
+
+- `media-src` must allow your media URLs.
+- `img-src` must allow any poster or thumbnail image URLs.
+- `connect-src` must allow HLS manifests, playlists, captions, and segment requests when using HLS playback.
+- `media-src blob:` is required when using the HLS player variants, which use MSE-backed playback.
+- `worker-src blob:` is required when using the `hls.js` player variants.
+- `style-src 'unsafe-inline'` is required for some player UI and HTML player styling behavior.
+
+## Recommended policy
+
+```http
+Content-Security-Policy:
+  script-src 'self';
+  style-src 'self' 'unsafe-inline';
+  img-src 'self' https: data: blob:;
+  media-src 'self' https: blob:;
+  connect-src 'self' https:;
+  worker-src 'self' blob:;
+```
+
+This policy assumes you bundle Video.js with your application or serve it from your own origin. If you load the player from a CDN, add that CDN’s origin to `script-src`.
+
+Replace broad sources such as `https:` with the exact origins your player uses. Remove sources your deployment does not need, and keep `blob:` only where your selected HLS renderer requires it.
+
+## Related pages
+
+### Guides
+
+- [Installation](./installation.md): Install Video.js packages and build an accessible, customizable video player with composable controls
+- [Self-host the player](./self-hosting.md): Serve the Video.js HTML player from your own origin for offline, air-gapped, or restricted-network deployments

package/docs/guides/controls.md

@@ -0,0 +1,196 @@
+# Automatically show and hide controls
+
+Show controls while the user is active, hide them during playback, and toggle them by touch.
+
+> **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
+
+Wrap your control UI in [`<media-controls>`](../reference/components/controls.md). It reads controls visibility from player state, so the whole control bar shows and hides as one unit.
+
+**index.html**
+
+```html
+<video-player class="video-player">
+  <media-container>
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
+
+    <media-controls>
+      <media-controls-backdrop class="controls-backdrop"></media-controls-backdrop>
+      <media-controls-content class="media-controls">
+        <media-controls-group class="controls-group" aria-label="Playback controls">
+          <media-play-button class="button media-play-button">
+            <span class="paused">Play</span>
+            <span class="playing">Pause</span>
+          </media-play-button>
+          <media-time class="time" type="current"></media-time>
+        </media-controls-group>
+      </media-controls-content>
+    </media-controls>
+  </media-container>
+</video-player>
+```
+
+**index.css**
+
+```css
+.video-player media-container {
+  position: relative;
+  display: block;
+}
+
+.video-player media-container video {
+  width: 100%;
+}
+
+.media-controls {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: flex-end;
+  padding: 12px;
+  pointer-events: none;
+  transition: opacity 0.25s;
+}
+
+.controls-backdrop {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  background: linear-gradient(to top, rgba(0, 0, 0, 0.45), transparent 45%);
+  opacity: 1;
+  transition: opacity 0.35s;
+}
+
+.controls-backdrop:not([data-visible]),
+.media-controls:not([data-visible]) {
+  opacity: 0;
+}
+
+.controls-group {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  pointer-events: auto;
+}
+
+.time {
+  display: inline-flex;
+  gap: 4px;
+  align-items: center;
+  padding-block: 8px;
+  padding-inline: 16px;
+  font-size: 14px;
+  color: black;
+  background: rgba(255, 255, 255, 0.75);
+  border: 1px solid rgba(255, 255, 255, 0.25);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+
+.button {
+  padding-block: 8px;
+  padding-inline: 16px;
+  font-size: 14px;
+  color: black;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.75);
+  border: 1px solid rgba(255, 255, 255, 0.25);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+
+.button .paused,
+.button .playing {
+  display: none;
+}
+
+.media-play-button[data-paused] .paused {
+  display: inline;
+}
+
+.media-play-button:not([data-paused]) .playing {
+  display: inline;
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/video/player';
+import '@videojs/html/ui/container';
+import '@videojs/html/ui/controls';
+import '@videojs/html/ui/controls-backdrop';
+import '@videojs/html/ui/controls-content';
+import '@videojs/html/ui/controls-group';
+import '@videojs/html/ui/play-button';
+import '@videojs/html/ui/time';
+```
+
+## How it works
+
+The [controls feature](../reference/api/feature-controls.md) tracks activity on the player container:
+
+- `userActive` is `true` while the user interacts — pointer movement, keyboard input, or focus — and flips to `false` after two seconds of inactivity.
+- `controlsVisible` derives from activity and playback: controls stay visible while paused or while a remote playback session is connecting or connected, regardless of idle state.
+- `toggleControls()` flips visibility, for wiring to custom triggers.
+
+On touch devices, a tap on the media toggles the controls instead of relying on pointer movement, and mid-gesture movement doesn’t flicker visibility.
+
+The feature needs the player container for activity tracking; without a container it stays inactive and warns in development.
+
+## Availability and constraints
+
+- Activity tracking listens on the player container, so controls placed outside it don’t keep the player “active” — put control UI inside the container.
+- Keyboard focus counts as activity: controls stay reachable for keyboard and assistive-technology users while focus is inside them.
+- Touch and mouse behave differently by design — mouse movement shows controls, touch requires a tap. Test both.
+- The idle delay is fixed at two seconds.
+
+## Common variations
+
+### Always-visible controls
+
+Set `visibility="always"` on [`<media-controls>`](../reference/components/controls.md). The controls stay visible and report the user as active while the feature keeps tracking activity for anything else that needs it. The packaged audio skins use this mode.
+
+```html
+<media-controls visibility="always">
+  <media-controls-content class="controls">...</media-controls-content>
+</media-controls>
+```
+
+### Custom show/hide styling
+
+Controls hide by state, so you own the transition. Style the visible and hidden states in CSS — fade, slide, or scale — driven by the component’s rendered state rather than re-implementing the idle timer.
+
+## Troubleshooting
+
+### Controls never hide
+
+The media is paused (controls intentionally stay visible), a remote playback session is active, an open menu or popover holds a controls lock, or something keeps triggering activity — for example a focused element inside the container receiving repeated events.
+
+### Controls don’t come back on touch
+
+A tap on the media toggles controls. If a custom overlay covers the media and swallows pointer events, taps never reach the container; let pointer events pass through decorative overlays.
+
+### Controls flicker on Android while tapping
+
+Use the skin gestures (`tap` with the `toggleControls` action) rather than adding your own tap handlers next to the built-in behavior; competing handlers invert each other. See [Add keyboard shortcuts and gestures](./keyboard-shortcuts.md).
+
+## Related pages
+
+### Components
+
+- [media-controls](../reference/components/controls.md): Container component for composing and auto-hiding video player controls on user interaction
+- [media-container](../reference/components/player-container.md): The player's visual and interaction surface for layout, fullscreen, focus, and user activity.
+
+### API
+
+- [Controls](../reference/api/feature-controls.md): User activity and controls visibility state for the player store
+
+### Guides
+
+- [Add keyboard shortcuts and gestures](./keyboard-shortcuts.md): Add keyboard shortcuts, tap and double-tap gestures, and on-screen feedback for input actions.
+- [Accessibility](./accessibility.md): How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player

package/docs/guides/customize-skins.md

@@ -0,0 +1,141 @@
+# Customize skins
+
+Style a packaged Video.js skin or add its source to change controls, layout, styles, and interactions
+
+Start with the path that matches the change you want:
+
+| If you want to… | Use this path |
+| --- | --- |
+| Change colors, typography, sizing, or how the poster fills the player | [Style a packaged skin](#style-a-packaged-skin). The skin stays in the Video.js package, and you set its supported CSS properties. |
+| Add, remove, rearrange, or deeply restyle controls; change layout or interactions | [Style skin source](#style-skin-source). The `shadcn` CLI adds the skin source to your project so you can change it. |
+
+## Style a packaged skin
+
+Use a packaged skin’s public settings to match it to your site without copying its source into your project.
+
+### Set the skin’s styles
+
+Packaged skins expose [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) for their supported visual changes. Set them on the skin or any element that contains it:
+
+```html
+<video-skin style="--media-accent-color: #f5c518; --media-border-radius: 1rem">
+  <video src="video.mp4"></video>
+</video-skin>
+```
+
+| Property name | What it changes | Value | Example |
+| --- | --- | --- | --- |
+| `--media-accent-color` | Slider fills, highlighted controls and menu items, and primary actions | [`<color>`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) | `#f5c518` |
+| `--media-accent-text-color` | Text and icons shown on the accent color | [`<color>`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) | `black` |
+| `--media-border-color` | The hairline around the player | [`<color>`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) | `transparent` |
+| `--media-border-radius` | The player corner radius | A valid [border-radius value](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/border-radius#values) | `1rem` |
+| `--media-font-family` | The player interface font stack | A valid [font-family value](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/font-family) | `Roboto, sans-serif` |
+| `--media-object-fit` | How the media and poster fill the player | A valid [object-fit value](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/object-fit) | `cover` |
+| `--media-object-position` | Where the media and poster sit when they do not fill the player | A valid [object-position value](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/object-position) | `top` |
+| `--media-scale-unit` | The base size for skin spacing, icons, and text | [`<length>`](https://developer.mozilla.org/en-US/docs/Web/CSS/length) | `1rem` |
+
+If you omit `--media-accent-text-color`, the skins choose a contrasting text color from `--media-accent-color` using [`contrast-color()`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/contrast-color). Set it only when you want a different result.
+
+The skins use [`Inter`](https://rsms.me/inter/) when your page loads it and fall back to the system UI font. Video.js does not load the webfont for you. Set `--media-font-family` to use another font.
+
+The media element and poster share `--media-object-fit` and `--media-object-position`, so a `cover` poster stays aligned with `cover` video. See [Add a poster and loading placeholder](./poster.md).
+
+### Set the color scheme
+
+The audio skins adapt their main palette for light and dark mode using [`light-dark()`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/light-dark). They read the inherited [`color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme), so set it on the player or an element that contains it:
+
+```css
+:root {
+  color-scheme: light dark;
+}
+```
+
+The video skins keep their dark controls in both color schemes. Only their hairline border follows the scheme, and `--media-border-color` replaces it.
+
+### Scale from the document font size
+
+The skins derive control spacing, icon sizes, and text from `--media-scale-unit`. It defaults to `16px`, so the player does not change with the document root font size or your app’s Tailwind spacing scale. Set it to `1rem` to make the interface scale from the document root font size:
+
+```css
+.player {
+  --media-scale-unit: 1rem;
+}
+```
+
+In fullscreen, the skins increase the unit up to 1.75 times on displays 1920 pixels and wider. This keeps controls legible from a distance.
+
+You can also add your own class names to the skins.
+
+### Know where packaged styling stops
+
+The properties above are the public styling settings for packaged skins. Do not depend on the elements, class names, or other custom properties inside a packaged skin. They may change between releases.
+
+Packaged video skins also let you replace the poster through the `poster` slot.
+
+See [`<media-poster>`](../reference/components/poster.md).
+
+Packaged skins do not provide settings for adding, removing, or rearranging controls, or for replacing built-in feedback and interactions. To make those changes, [add the source for the closest skin to your project](#style-skin-source) and edit it directly.
+
+## Style skin source
+
+If a packaged skin is close to the interface you want, add its source to your project and edit it. The source contains the skin’s controls, layout, styles, and interactions.
+
+Video.js publishes skin source in an installable catalog. The [`shadcn` CLI](https://ui.shadcn.com/docs/cli) adds that source to your project, whether you use React or HTML.
+
+The selected skin is generally placed under `components/videojs/<preset>`, with shared controls and styles alongside it under `components/videojs`. The exact root follows the components alias in `components.json`. The CLI can also install package dependencies, update `components.json`, and add shared styles to your main CSS file.
+
+> **Note**
+>
+> Commit your work before installing or updating source. You can then review every file the CLI adds or replaces.
+
+### Add the source
+
+The Shadcn installation guide handles project setup, lets you choose the skin and styling, and shows how to use the installed source in a working player.
+
+- [Install Video.js with Shadcn](./installation-shadcn.md): Add editable skin source and build a working React or HTML player
+
+### Use the installed skin
+
+The skin directory contains `skin.html`, `skin.ts`, and `skin.css`. Keep importing the player and media from `@videojs/html`. Import the installed `skin.ts` once, then paste the markup from `skin.html` inside your player around the media element.
+
+### Edit the installed files
+
+Start with the file that owns the change you want:
+
+| Goal | Where to start |
+| --- | --- |
+| Add, remove, or rearrange controls | `skin.html` |
+| Change default colors, surfaces, shadows, sizes, or motion across skins | `components/videojs/styles/themes/theme.css` |
+| Change only the Minimal theme or one media preset | `components/videojs/styles/themes/minimal.css`, `components/videojs/styles/video/theme.css`, or `components/videojs/styles/audio/theme.css` |
+| Change one control’s appearance | That control’s classes or stylesheet |
+| Change one control’s interaction | That control’s module |
+
+The `skin.html` file contains the layout. The `skin.ts` module registers the custom elements and loads `skin.css`. Elements use class names that start with `media-`; change a class in `skin.html` or a rule in the stylesheet to change one part of the interface.
+
+### Inspect or update the skin source
+
+Use the CLI’s `search` command to find source and `view` to inspect it before installation:
+
+```bash
+npx shadcn@latest search @videojs --query volume
+npx shadcn@latest view @videojs/video
+```
+
+Installed files belong to your project, so an update replaces your local copy. Commit your changes, reinstall with `--overwrite`, and review the resulting version-control diff before keeping it:
+
+```bash
+npx shadcn@latest add @videojs/video --overwrite
+```
+
+To understand how skins fit into Video.js, read [Skins](./skins.md). To create a control instead of editing one, follow [Build your own component](./build-your-own-component.md).
+
+## Related pages
+
+### Components
+
+- [video-skin](../reference/components/video-skin.md): The video preset's default skin with the modern, frosted look
+
+### Guides
+
+- [Skins](./skins.md): Packaged player designs that include both UI components and their styles.
+- [Build your own UI component](./build-your-own-component.md): Create custom player controls that read state, dispatch actions, and stay accessible.

package/docs/guides/features.md

@@ -0,0 +1,107 @@
+# Features
+
+The state and actions each feature adds to the player
+
+Not every player needs to support every use case. To address this, Video.js has a concept of **features** — self-contained units of player functionality. Each one adds state properties and actions to the player. For example, “playback” adds `paused` and `play()`, “volume” adds `volume` and `setVolume()`, and so on.
+
+## Feature bundles and presets
+
+You probably don’t want to hand-pick every feature your player needs. A **feature bundle** groups the features needed for a specific use case into a single array.
+
+For example, if you import `<video-player>` from the `/video` path, you will have playback, volume, time, fullscreen, and more already enabled.
+
+```html
+<script type="module">
+  import '@videojs/html/video/player';
+  import '@videojs/html/video/skin';
+</script>
+<video-player>
+  <video-skin>
+    <video src="movie.mp4"></video>
+  </video-skin>
+</video-player>
+```
+
+Feature bundles are usually paired with specific skins and media elements in a **preset**. To learn more about this, and the available presets, you’ll want to check out the presets guide.
+
+- [Learn more about presets](./presets.md)
+
+## Individual features
+
+If you’re not using presets, you can create a player that has individual features.
+
+```ts
+import { controlsFeature, createPlayer, playbackFeature, timeFeature, volumeFeature } from '@videojs/html';
+
+const { PlayerElement: MyPlayer } = createPlayer({
+  features: [playbackFeature, volumeFeature, timeFeature, controlsFeature],
+});
+
+customElements.define('my-player', MyPlayer);
+```
+
+## Extended feature bundles
+
+Since feature bundles are just an array of features under the hood, it doesn’t take much to extend one. For example, if you were using the `/background` preset and wanted a play button on your background video, you might add the playback feature.
+
+```ts
+import { createPlayer, playbackFeature } from '@videojs/html';
+import { backgroundFeatures } from '@videojs/html/background';
+
+const { PlayerElement: MyPlayer } = createPlayer({
+  features: [...backgroundFeatures, playbackFeature],
+});
+
+customElements.define('my-player', MyPlayer);
+```
+
+## Features inside components
+
+You can access feature state and actions through [`PlayerController`](../reference/api/player-controller.md) and pre-built feature selectors (e.g. [`selectPlayback`](../reference/api/feature-playback.md), [`selectVolume`](../reference/api/feature-volume.md)):
+
+```ts
+import { selectPlayback } from '@videojs/html';
+
+// Subscribe to feature state (triggers element updates on change)
+readonly #playback = new PlayerController(this, selectPlayback);
+
+// Read state and call actions
+const media = this.#playback.value;
+if (media?.paused) media.play();
+```
+
+## Feature availability
+
+Volume, fullscreen, and picture-in-picture expose availability properties because platform support varies. Volume has two independent properties: `volumeAvailability` for changing the volume level and `mutedAvailability` for toggling mute. For example, iOS Safari allows muting but doesn’t allow programmatic volume control.
+
+| Value | Meaning |
+| --- | --- |
+| `'available'` | Ready to use |
+| `'unavailable'` | Could work, not ready yet |
+| `'unsupported'` | Platform can never do this |
+
+Components that depend on availability (like [`<media-mute-button>`](../reference/components/mute-button.md), [`<media-pip-button>`](../reference/components/pip-button.md), and [`<media-fullscreen-button>`](../reference/components/fullscreen-button.md)) handle the three states for you:
+
+- **`unsupported`** — the element receives the native `hidden` attribute (and `data-hidden`). No CSS needed.
+- **`unavailable`** — the presentation controls stay hidden while capability detection is unresolved. Cast remains visible but disabled when its API is supported and no device is reachable.
+- **`disabled` attribute** — an available button stays visible and focusable with `aria-disabled="true"` plus `data-disabled` for styling.
+- **`available`** — fully interactive.
+
+Use `data-disabled` to style the non-interactive state:
+
+```css
+media-pip-button[data-disabled] {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+```
+
+You can also check availability in JS:
+
+```ts
+const media = this.#pip.value;
+
+if (media?.pipAvailability !== 'available') {
+  this.hidden = true;
+}
+```