@videojs/react 10.0.0-rc.2 → 10.0.0-rc.3

package/docs/guides/picture-in-picture.md

@@ -0,0 +1,149 @@
+# Use picture-in-picture
+
+Pop the video into a floating window, with availability detection and state that tracks every entry path.
+
+> **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 [PiPButton](../reference/components/pip-button.md). It requests and exits picture-in-picture, reflects the current state, and renders nothing when picture-in-picture is unsupported.
+
+**App.tsx**
+
+```tsx
+import { Container, createPlayer, PiPButton } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+export default function BasicUsage() {
+  return (
+    <Player>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
+        <PiPButton
+          className="media-pip-button"
+          render={(props, state) => <button {...props}>{state.pip ? 'Exit PiP' : 'Enter PiP'}</button>}
+        />
+      </Container>
+    </Player>
+  );
+}
+```
+
+**App.css**
+
+```css
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.media-pip-button {
+  position: absolute;
+  right: 10px;
+  bottom: 10px;
+  padding-block: 8px;
+  padding-inline: 20px;
+  color: black;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.7);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+```
+
+## How it works
+
+The [picture-in-picture feature](../reference/api/feature-pip.md) puts three things in player state.
+
+`pip` is `true` while the video is in a floating window. It tracks every way in and out — your button, the native controls, or a control the browser adds on its own.
+
+`pipAvailability` answers “can I offer this?” It starts as `'unavailable'`. Once the feature attaches to a media element, it settles to `'available'` or `'unsupported'`.
+
+`requestPictureInPicture()`, `exitPictureInPicture()`, and `togglePictureInPicture()` change the presentation. If the browser blocks a request, the returned promise rejects. In a browser with no picture-in-picture API, the actions resolve without changing anything.
+
+Picture-in-picture and fullscreen are exclusive: requesting one exits the other first.
+
+## Availability and constraints
+
+- Show picture-in-picture controls only when `pipAvailability` is `'available'`. PiPButton handles this for you.
+- Requests must come from a user gesture; browsers reject requests outside one.
+- Firefox 153 (July 2026) added the programmatic picture-in-picture API. Earlier versions, including Firefox ESR 140, report `'unsupported'` even though they offer their own built-in picture-in-picture toggle to users.
+- On iOS, picture-in-picture is supported on iPhone and iPad through the WebKit presentation mode; the player handles this path for you.
+- The browser owns the floating window: its size, position, and built-in controls aren’t yours to style.
+- The user can close the window or return the video at any time. React to `pip` state instead of assuming your button is the only entry and exit.
+
+## Common variations
+
+### Request picture-in-picture from app logic
+
+Enter picture-in-picture when the user scrolls the player out of view or navigates within your app. This still requires a recent user gesture in most browsers, so tie it to an interaction:
+
+```tsx
+import { Container } from '@videojs/react';
+import { usePlayer, Video, VideoPlayer } from '@videojs/react/video';
+
+function WatchElsewhereButton() {
+  const store = usePlayer();
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        store.requestPictureInPicture().catch(() => {
+          // Rejected: no video data yet, or blocked by the browser.
+        });
+      }}
+    >
+      Keep watching while you browse
+    </button>
+  );
+}
+
+export default function App() {
+  return (
+    <VideoPlayer>
+      <Container>
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline />
+        <WatchElsewhereButton />
+      </Container>
+    </VideoPlayer>
+  );
+}
+```
+
+## Troubleshooting
+
+### The picture-in-picture button doesn’t render
+
+`pipAvailability` is `'unsupported'` — the browser has no programmatic picture-in-picture API (Firefox before 153), or the media isn’t a video.
+
+### The request rejects
+
+The video has no data yet (wait for it to be ready), the call wasn’t tied to a user gesture, or the browser blocked it. Handle the rejection rather than assuming entry succeeded.
+
+### State is wrong after the user closes the floating window
+
+Read `pip` from player state instead of tracking entry and exit yourself; it stays in sync with every path in and out of picture-in-picture.
+
+## Related pages
+
+### Components
+
+- [PiPButton](../reference/components/pip-button.md): Accessible picture-in-picture toggle button with keyboard support and state reflection
+
+### API
+
+- [Picture-in-picture](../reference/api/feature-pip.md): Picture-in-picture state and actions for the player store
+
+### Guides
+
+- [Go fullscreen and lock orientation](./fullscreen.md): Present the player fullscreen with custom controls intact, and lock screen orientation on mobile.
+- [Cast to AirPlay and Chromecast](./casting.md): Send playback to AirPlay and Google Cast devices, with availability detection and connection state.

package/docs/guides/playback-errors.md

@@ -0,0 +1,124 @@
+# Handle playback errors
+
+Display playback failures, report them, and choose a useful recovery action.
+
+Display playback failures instead of leaving a dead player, report the failure when you need diagnostics, and give users a useful next step.
+
+> **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
+
+Render an [ErrorDialog](../reference/components/error-dialog.md) inside the player container. It reads error state, presents the failure, and dismisses cleanly. The prebuilt skins include one.
+
+```tsx
+import { Container, ErrorDialog } from '@videojs/react';
+import { Video, VideoPlayer } from '@videojs/react/video';
+
+export default function App() {
+  return (
+    <VideoPlayer>
+      <Container>
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline />
+
+        <ErrorDialog.Root>
+          <ErrorDialog.Popup className="media-error">
+            <ErrorDialog.Title />
+            <ErrorDialog.Description />
+            <ErrorDialog.Close>Dismiss</ErrorDialog.Close>
+          </ErrorDialog.Popup>
+        </ErrorDialog.Root>
+      </Container>
+    </VideoPlayer>
+  );
+}
+```
+
+## How it works
+
+The [error feature](../reference/api/feature-error.md) mirrors the media element’s error into player state:
+
+- `error` holds the media’s error — `code`, `message` — or `null` when there is none.
+- `dismissError()` clears the error from player state (the media element keeps its own error until a new load).
+- Loading a new source resets `error` to `null` automatically.
+
+The dialog owns presentation, not recovery. Decide the next step in your application: let the user dismiss the message, choose another item, refresh an expired URL, or contact support.
+
+## Availability and constraints
+
+- For a terminal failure, load a new or refreshed source to recover. An aborted load or an adapter-specific error may have different behavior.
+- Standard media error codes distinguish broad classes — aborted, network, decode, and source-not-supported — rather than root causes. A media adapter can report its own numeric code too.
+- Streaming engines handle recoverable segment and network failures before surfacing a terminal error. Do not layer a generic same-source retry loop on top of the engine.
+- Once the player attaches to the media element, errors land in state even before any UI renders (bad URL at mount); make sure your error surface renders regardless of playback state.
+
+## Common variations
+
+### Offer an application-specific next step
+
+Use the error code and your product context to choose the action. A live event can link to its status page, an authenticated app can refresh an expired playback URL, and a playlist can offer the next item. Keep that action outside `ErrorDialog`; the dialog can close after your application has handled it.
+
+### Report errors to monitoring
+
+Subscribe to error state and forward new errors to your monitoring service with the source URL and `error.code`. A media error does not automatically appear in JavaScript exception monitoring.
+
+Place a reporter inside `VideoPlayer`, alongside the skin or your custom controls:
+
+```tsx
+import { useEffect } from 'react';
+import { selectError } from '@videojs/react';
+import { usePlayer } from '@videojs/react/video';
+
+function PlaybackErrorReporter({
+  onError,
+}: {
+  onError: (error: { code: number; message: string }) => void;
+}) {
+  const error = usePlayer(selectError)?.error;
+
+  useEffect(() => {
+    if (error) onError(error);
+  }, [error, onError]);
+
+  return null;
+}
+```
+
+Pass a stable `onError` function that sends the error and current source URL to your monitoring service. The effect runs when the error value changes, not on every player state update.
+
+### Diagnose a reported failure
+
+Start with `error.code` and the affected source URL. Check the browser’s network panel for failed media requests, response status, redirects, CORS headers, and expired credentials. If requests succeed, check the file’s container and codecs against the chosen media component. For HLS or DASH, inspect the streaming engine’s diagnostics for segment and manifest failures; the player error often names only the final outcome.
+
+## Troubleshooting
+
+### The player is black and silent with no error
+
+Not every dead player is a media error — autoplay blocking and an unset source produce no error. Check `error`, `source`, and `paused` in player state to tell them apart. If `play()` rejects with `NotAllowedError`, see [Autoplay](./autoplay.md).
+
+### A `VJS8_LEGACY_*` exception appears
+
+These codes identify Video.js 8 APIs used with the Video.js 10 `video.js` package. Look up the code in the [error code reference](../reference/api/error-codes.md) for its trigger and v10 equivalent. The player `error` state covered in this guide receives media playback errors after setup.
+
+### Error code says the source isn’t supported
+
+The browser can’t play the format through this media element. HLS in a plain video element outside Safari is the classic case; use the matching streaming media element. See [Media sources](./media-sources.md).
+
+### Reopening the source produces the same error
+
+The failure is probably permanent for that source, such as a 404, revoked token, unsupported codec, or CORS response. Fix or replace the source instead of repeatedly loading the same URL.
+
+## Related pages
+
+### Components
+
+- [BufferingIndicator](../reference/components/buffering-indicator.md): Loading indicator that displays when the video player is buffering or waiting for data
+
+### API
+
+- [Error](../reference/api/feature-error.md): Media error state and actions for the player store
+
+### Guides
+
+- [Media sources](./media-sources.md): Set what a media element plays and how its engine plays it with the structured source property
+- [Autoplay](./autoplay.md): Start playback automatically and handle browser autoplay restrictions.

package/docs/guides/poster.md

@@ -0,0 +1,222 @@
+# Add a poster and loading placeholder
+
+Set the image shown before playback, then add a lightweight placeholder while it loads
+
+A poster is the image shown before your video plays. There are several places to set one, so work down this list and stop at the first step that fits:
+
+1. **Let the media provide it.** Some media components create a poster from the source, so there is nothing extra to host or keep in sync.
+2. **Set `poster` on the player.** With a packaged skin, that is all a static image needs.
+3. **Take control of the image** when you need a framework image component, a `<picture>` element, or a loading placeholder. The skin renders your image instead of its own.
+4. **Keep it working after [adding the skin source to your project](./customize-skins.md#style-skin-source).** The player’s `poster` still reaches the Poster component your skin renders, or you can set the image’s source yourself.
+
+## Let the media provide a poster
+
+Some media components choose a poster for you. For example, `MuxVideo` creates one from its playback ID:
+
+Install the React façade and the Mux playback adapter:
+
+```bash
+pnpm add @videojs/react @videojs/mux-video
+```
+
+```tsx
+import '@videojs/react/video/skin.css';
+import { MuxVideo } from '@videojs/react/media/mux-video';
+import { VideoPlayer, VideoSkin } from '@videojs/react/video';
+
+export function MyPlayer() {
+  return (
+    <VideoPlayer>
+      <VideoSkin>
+        <MuxVideo
+          source={{
+            playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
+            poster: { time: 2 },
+          }}
+          playsInline
+        />
+      </VideoSkin>
+    </VideoPlayer>
+  );
+}
+```
+
+## Set a poster on the player
+
+When the media has no poster of its own, set the player’s `poster` to an image URL:
+
+```tsx
+import '@videojs/react/video/skin.css';
+import { Video, VideoPlayer, VideoSkin } from '@videojs/react/video';
+
+export function MyPlayer() {
+  return (
+    <VideoPlayer poster="/poster.jpg">
+      <VideoSkin>
+        <Video src="/video.mp4" playsInline />
+      </VideoSkin>
+    </VideoPlayer>
+  );
+}
+```
+
+If you use a ready-made skin, it includes [Poster](../reference/components/poster.md) and shows the image automatically. If you build your own UI, add Poster yourself. It hides after the user plays or seeks.
+
+When the player and the media component both choose a poster, the player’s `poster` wins. See [Metadata](../reference/api/feature-metadata.md) for how the player combines those values.
+
+Posters are decorative by default, with an empty `alt`. If the image communicates something that is not available elsewhere, add `alt` text when you customize the poster image.
+
+## Take control of the poster image
+
+The packaged skins also accept an image of your own, for when a plain `<img>` is not enough:
+
+Pass `renderPoster` to the skin. Video.js passes the poster URL as `src` alongside the rest of the image props; `src` stays `undefined` until a poster URL resolves. That fits a framework image component:
+
+```tsx
+import '@videojs/react/video/skin.css';
+import { Video, VideoPlayer, VideoSkin } from '@videojs/react/video';
+import NextImage from 'next/image';
+
+export function MyPlayer() {
+  return (
+    <VideoPlayer poster="/poster.jpg">
+      <VideoSkin
+        renderPoster={({ src, ...props }) =>
+          src ? <NextImage {...props} src={src} alt="" fill /> : null
+        }
+      >
+        <Video src="/video.mp4" playsInline />
+      </VideoSkin>
+    </VideoPlayer>
+  );
+}
+```
+
+## Add a loading placeholder
+
+A placeholder is a tiny preview that appears while the poster downloads, so a slow poster does not leave the player as empty space. Keep it small enough to include with the page, such as a short data URL. Add it to the customized image from the previous section.
+
+### Use your framework’s image component
+
+If your image component supports placeholders, pass yours through `renderPoster`:
+
+```tsx
+import '@videojs/react/video/skin.css';
+import { Video, VideoPlayer, VideoSkin } from '@videojs/react/video';
+import NextImage from 'next/image';
+
+export function MyPlayer() {
+  return (
+    <VideoPlayer poster="/poster.jpg">
+      <VideoSkin
+        renderPoster={({ src, ...props }) =>
+          src ? (
+            <NextImage
+              {...props}
+              src={src}
+              alt=""
+              fill
+              placeholder="blur"
+              blurDataURL="data:image/webp;base64,…"
+            />
+          ) : null
+        }
+      >
+        <Video src="/video.mp4" playsInline />
+      </VideoSkin>
+    </VideoPlayer>
+  );
+}
+```
+
+Next.js generates blur data for static imports. Here, the poster URL arrives while the player runs, so provide `blurDataURL` yourself.
+
+### Use a plain image
+
+For more control, add the placeholder as a background on the image that `VideoSkin` draws:
+
+```tsx
+import '@videojs/react/video/skin.css';
+import { Video, VideoPlayer, VideoSkin } from '@videojs/react/video';
+
+export function MyPlayer() {
+  return (
+    <VideoPlayer poster="/poster.jpg">
+      <VideoSkin
+        renderPoster={(props) => (
+          <img
+            {...props}
+            style={{
+              ...props.style,
+              background:
+                "url('data:image/webp;base64,…') var(--media-object-position, center) / contain no-repeat",
+            }}
+          />
+        )}
+      >
+        <Video src="/video.mp4" playsInline />
+      </VideoSkin>
+    </VideoPlayer>
+  );
+}
+```
+
+The examples use `contain` for both images. Use `cover` for both when the poster should fill the player. Keeping the same size and position prevents the image from jumping when the poster appears.
+
+## Set the poster after adding skin source
+
+Adding the skin source to your project changes nothing about the first two approaches: the player’s `poster`, or the poster the media provides, still reaches the [Poster](../reference/components/poster.md) component your skin renders.
+
+`Poster.Root` owns visibility and loading state. `Poster.Image` renders the image and fills its `src` from the player, so `srcSet`, `sizes`, `loading`, and the rest of the image attributes are yours. Provide your own `src` or `srcSet` and Video.js leaves the image alone.
+
+When your UI already includes Poster, apply a placeholder through the image’s `render` prop:
+
+```tsx
+<Poster.Root>
+  <Poster.Image
+    render={(props) => (
+      <img
+        {...props}
+        style={{
+          ...props.style,
+          background:
+            "url('data:image/webp;base64,…') var(--media-object-position, center) / contain no-repeat",
+        }}
+      />
+    )}
+  />
+</Poster.Root>
+```
+
+## Troubleshooting
+
+### No poster appears
+
+Check that the player has a `poster` or that the media component can create one from its source.
+
+### The final poster never appears
+
+Pass the `src` from `renderPoster` to your image. If your image component requires a source, return `null` until `src` is available.
+
+### The placeholder and poster use different crops
+
+Use the same fit for both images: pair `background-size: contain` with `object-fit: contain`, or use `cover` for both.
+
+### The placeholder adds too much page weight
+
+Use fewer pixels and stronger compression. The placeholder only needs to suggest the poster’s color and shape until the full image appears.
+
+## Related pages
+
+### Components
+
+- [Poster](../reference/components/poster.md): Poster image component that displays a thumbnail until video playback starts
+
+### API
+
+- [Metadata](../reference/api/feature-metadata.md): Resolved title and poster values for the player store
+
+### Guides
+
+- [Customize skins](./customize-skins.md#style-a-packaged-skin): Style a packaged Video.js skin or add its source to change controls, layout, styles, and interactions
+- [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/presets.md

@@ -0,0 +1,94 @@
+# Presets
+
+Pre-packaged player configurations that bundle state management, skins, and media elements for specific use cases.
+
+A **preset** packages what you need for a specific player use case. It can include special [state management](./features.md), one or more [skins](./skins.md) for UI, and specific media elements. Instead of assembling these pieces individually, you pick a preset that matches what you’re building.
+
+For example, the `@videojs/react/background` preset includes a media element with autoplay, mute, and loop built in, a skin with no controls, and just the features needed to power them:
+
+**App.tsx**
+
+```tsx
+import { BackgroundVideo, BackgroundVideoPlayer, BackgroundVideoSkin } from '@videojs/react/background';
+import '@videojs/react/background/skin.css';
+
+function Hero() {
+  return (
+    <BackgroundVideoPlayer>
+      <BackgroundVideoSkin>
+        <BackgroundVideo src="hero.mp4" />
+      </BackgroundVideoSkin>
+    </BackgroundVideoPlayer>
+  );
+}
+```
+
+## Available presets
+
+The default presets are `/video` and `/audio`. These cover the baseline controls you’d expect from the HTML `<video>` and `<audio>` tags. Beyond the defaults, presets target more specific use cases — the `/background` preset, for example, needs layout but not controls. Over time we’ll add more: short-form players, podcast players, TV streaming players, and others.
+
+| Import | Description | Details |
+| --- | --- | --- |
+| `@videojs/react/video` | General-purpose video player preset with full playback controls. | **Feature bundle:** `videoFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [playbackRate](../reference/api/feature-playback-rate.md), [quality](../reference/api/feature-quality.md), [audioTrack](../reference/api/feature-audio-track.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [fullscreen](../reference/api/feature-fullscreen.md), [pip](../reference/api/feature-pip.md), [remotePlayback](../reference/api/feature-remote-playback.md), [controls](../reference/api/feature-controls.md), [textTrack](../reference/api/feature-text-tracks.md), [error](../reference/api/feature-error.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<MinimalVideoSkin>` with `import '@videojs/react/video/minimal-skin.css';`, `<VideoSkin>` with `import '@videojs/react/video/skin.css';`; **Default media element:** `<Video>` |
+| `@videojs/react/audio` | Audio-only player preset with playback and volume controls. | **Feature bundle:** `audioFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [playbackRate](../reference/api/feature-playback-rate.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [error](../reference/api/feature-error.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<MinimalAudioSkin>` with `import '@videojs/react/audio/minimal-skin.css';`, `<AudioSkin>` with `import '@videojs/react/audio/skin.css';`; **Default media element:** `<Audio>` |
+| `@videojs/react/background` | Ambient background video preset with no user controls. | **Feature bundle:** `backgroundFeatures`; **Features:** –; **Skins:** `<BackgroundVideoSkin>` with `import '@videojs/react/background/skin.css';`; **Default media element:** `<BackgroundVideo>` |
+| `@videojs/react/live-audio` | Live audio player preset — `audio` minus playback rate, plus the live feature, with a skin that swaps the time slider and time displays for a Live button. | **Feature bundle:** `liveAudioFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [error](../reference/api/feature-error.md), [live](../reference/api/feature-live.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<MinimalLiveAudioSkin>` with `import '@videojs/react/live-audio/minimal-skin.css';`, `<LiveAudioSkin>` with `import '@videojs/react/live-audio/skin.css';`; **Default media element:** `<Audio>` |
+| `@videojs/react/live-video` | Live video player preset — `video` minus playback rate, quality selection, and audio-track selection, plus the live feature, with a skin that swaps the time slider and time displays for a Live button. | **Feature bundle:** `liveVideoFeatures`; **Features:** [playback](../reference/api/feature-playback.md), [volume](../reference/api/feature-volume.md), [time](../reference/api/feature-time.md), [source](../reference/api/feature-source.md), [buffer](../reference/api/feature-buffer.md), [fullscreen](../reference/api/feature-fullscreen.md), [pip](../reference/api/feature-pip.md), [remotePlayback](../reference/api/feature-remote-playback.md), [controls](../reference/api/feature-controls.md), [textTrack](../reference/api/feature-text-tracks.md), [error](../reference/api/feature-error.md), [live](../reference/api/feature-live.md), [metadata](../reference/api/feature-metadata.md); **Skins:** `<MinimalLiveVideoSkin>` with `import '@videojs/react/live-video/minimal-skin.css';`, `<LiveVideoSkin>` with `import '@videojs/react/live-video/skin.css';`; **Default media element:** `<Video>` |
+
+## What’s in a preset
+
+Each React preset exports a named, preconfigured player component and typed `usePlayer` hook, plus the building blocks needed to extend its features, add its skin source to your project, or swap its media element:
+
+- **Player** — A player component named for the preset, such as `VideoPlayer`, already configured with the preset’s feature bundle.
+- **Typed hook** — A `usePlayer` hook whose state and actions match the preset.
+- **Feature bundle** — An array of [features](./features.md) that define the player’s state and actions. For example, the video feature bundle includes playback, volume, time, fullscreen, and more.
+- **Skins** — Pre-built UIs designed for that feature bundle. For example, a video skin renders fullscreen and PiP controls because the video feature bundle includes those features. An audio skin doesn’t.
+- **Media element** — A media component suited to the use case. For example, the background video element bakes in autoplay, mute, and loop.
+
+These parts aren’t equally tied together. Skins depend tightly on their feature bundle — a skin expects specific features to exist. Media elements are more interchangeable — you can swap in an HLS or DASH provider without changing your skin or features.
+
+## Customizing a preset
+
+You can customize a preset in three ways: extend its feature bundle, add its skin source to your project, or swap its media element.
+
+### Extend the feature bundle
+
+Add features to a preset’s feature bundle to enable new functionality. For example, adding playback controls to a background video:
+
+**App.tsx**
+
+```tsx
+import { Container, createPlayer, playbackFeature, PlayButton } from '@videojs/react';
+import { backgroundFeatures, BackgroundVideo } from '@videojs/react/background';
+
+const { Player } = createPlayer({
+  features: [...backgroundFeatures, playbackFeature],
+});
+
+function Hero() {
+  return (
+    <Player>
+      <Container>
+        <BackgroundVideo src="hero.mp4" />
+        <PlayButton />
+      </Container>
+    </Player>
+  );
+}
+```
+
+### Skin source
+
+If a preset’s skin is close but not quite right, [add its source to your project](./customize-skins.md#style-skin-source) and customize its components and styles.
+
+### Swap the media element
+
+A preset’s default media element is just the starting point. You can replace it with any compatible media provider. For example, using an HLS source with the video preset:
+
+```tsx
+<VideoPlayer>
+  <VideoSkin>
+    <HlsJsVideo src="https://example.com/stream.m3u8" />
+  </VideoSkin>
+</VideoPlayer>
+```