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

package/docs/reference/components/tooltip.md

@@ -0,0 +1,369 @@
+# Tooltip
+
+A tooltip component for displaying contextual labels on hover and focus
+
+## Import
+
+```tsx
+import { Tooltip } from '@videojs/react';
+```
+
+## Anatomy
+
+```tsx
+<Tooltip.Provider>
+  <Tooltip.Root>
+    <Tooltip.Trigger>Hover me</Tooltip.Trigger>
+    <Tooltip.Popup>
+      <Tooltip.Arrow />
+      <Tooltip.Label>Label text</Tooltip.Label>
+      <Tooltip.Shortcut>K</Tooltip.Shortcut>
+    </Tooltip.Popup>
+  </Tooltip.Root>
+</Tooltip.Provider>
+```
+
+## Behavior
+
+Displays a short label anchored to a trigger element. Opens after a configurable `delay` (default 600ms) on hover or immediately on focus. Closes when the pointer leaves or focus moves away, with an optional `closeDelay`.
+
+The `side` and `align` props control the preferred placement relative to the trigger. When the preferred side overflows the positioning boundary, the tooltip uses the opposite side if it has more space. Positioning uses CSS Anchor Positioning where supported, with a JavaScript measurement fallback.
+
+The component is composed from six parts: `Root` manages state and context, `Trigger` renders a button that activates the tooltip, `Popup` contains the label content, `Label` renders the tooltip body, `Shortcut` renders an optional keyboard hint, and `Arrow` renders a decorative pointer. Wrap multiple tooltips in a `Tooltip.Provider` to coordinate open/close timing across a group — once a tooltip becomes visible, adjacent tooltips open instantly within the `timeout` window, skipping the normal `delay`.
+
+Tooltips inside a [player container](./player-container.md) also observe its popup group. By default, a tooltip does not open—or closes if already open—while a menu or popover attached to the same trigger is open. Set `sticky` when the tooltip should remain visible with that trigger’s popup.
+
+`Tooltip.Provider` coordinates tooltip delay timing only; it does not replace the container’s popup group.
+
+## Styling
+
+Use [CSS custom properties](#css-custom-properties) for positioning offsets:
+
+React renders standard DOM elements. Add a `className` to style them:
+
+```css
+.tooltip-popup {
+  --media-tooltip-side-offset: 8px;
+  --media-tooltip-align-offset: 0px;
+  --media-tooltip-boundary-offset: 8px;
+}
+```
+
+Style based on open state, rendered side, and transition phases. `data-side` reflects the rendered side and can differ from the preferred `side` prop after collision handling:
+
+```css
+.tooltip-popup[data-open] {
+  display: block;
+}
+.tooltip-popup[data-starting-style] {
+  opacity: 0;
+}
+.tooltip-popup[data-ending-style] {
+  opacity: 0;
+}
+.tooltip-popup[data-side="top"] {
+  transform-origin: bottom center;
+}
+.tooltip-popup[data-side="bottom"] {
+  transform-origin: top center;
+}
+```
+
+## Accessibility
+
+Tooltips are visual-only, supplementary labels. The popup renders with `role="presentation"` and is not referenced by the trigger with `aria-describedby`. Give the trigger its own accessible name instead of relying on tooltip content. Built-in media buttons already expose a state-aware `aria-label`, and their tooltips reuse that translated label. Tooltips still open on focus so keyboard users who can see the label receive the same visual hint.
+
+## Examples
+
+### Basic Usage
+
+**App.tsx**
+
+```tsx
+import { Tooltip } from '@videojs/react';
+
+export default function BasicUsage() {
+  return (
+    <div className="demo">
+      <Tooltip.Root>
+        <Tooltip.Trigger className="trigger">Hover me</Tooltip.Trigger>
+        <Tooltip.Popup className="media-tooltip">
+          <Tooltip.Arrow className="arrow" />
+          <Tooltip.Label>Tooltip content</Tooltip.Label>
+        </Tooltip.Popup>
+      </Tooltip.Root>
+    </div>
+  );
+}
+```
+
+**App.css**
+
+```css
+.demo {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 40px 24px;
+}
+
+.trigger {
+  padding: 6px 16px;
+  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);
+}
+
+.media-tooltip {
+  --media-tooltip-side-offset: 8px;
+  padding: 4px 10px;
+  margin: 0;
+  font-size: 13px;
+  color: white;
+  white-space: nowrap;
+  pointer-events: none;
+  background: rgba(0, 0, 0, 0.85);
+  border: 0;
+  border-radius: 6px;
+  backdrop-filter: blur(10px);
+}
+
+.arrow {
+  fill: rgba(0, 0, 0, 0.85);
+}
+```
+
+### Grouping
+
+Wrap multiple tooltips in a `Tooltip.Provider` to share a delay group. Once a tooltip becomes visible, adjacent tooltips open instantly within the `timeout` window, skipping the normal `delay`.
+
+**App.tsx**
+
+```tsx
+import { Tooltip } from '@videojs/react';
+
+export default function Grouping() {
+  return (
+    <div className="demo">
+      <Tooltip.Provider>
+        <Tooltip.Root>
+          <Tooltip.Trigger className="trigger">Play</Tooltip.Trigger>
+          <Tooltip.Popup className="media-tooltip">
+            <Tooltip.Arrow className="arrow" />
+            <Tooltip.Label>Play video</Tooltip.Label>
+          </Tooltip.Popup>
+        </Tooltip.Root>
+        <Tooltip.Root>
+          <Tooltip.Trigger className="trigger">Mute</Tooltip.Trigger>
+          <Tooltip.Popup className="media-tooltip">
+            <Tooltip.Arrow className="arrow" />
+            <Tooltip.Label>Mute audio</Tooltip.Label>
+          </Tooltip.Popup>
+        </Tooltip.Root>
+        <Tooltip.Root>
+          <Tooltip.Trigger className="trigger">Fullscreen</Tooltip.Trigger>
+          <Tooltip.Popup className="media-tooltip">
+            <Tooltip.Arrow className="arrow" />
+            <Tooltip.Label>Enter fullscreen</Tooltip.Label>
+          </Tooltip.Popup>
+        </Tooltip.Root>
+      </Tooltip.Provider>
+    </div>
+  );
+}
+```
+
+**App.css**
+
+```css
+.demo {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 40px 24px;
+}
+
+.trigger {
+  padding: 6px 16px;
+  color: black;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.7);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  backdrop-filter: blur(10px);
+}
+
+.media-tooltip {
+  --media-tooltip-side-offset: 8px;
+  padding: 4px 10px;
+  margin: 0;
+  font-size: 13px;
+  color: white;
+  white-space: nowrap;
+  pointer-events: none;
+  background: rgba(0, 0, 0, 0.85);
+  border: 0;
+  border-radius: 6px;
+  backdrop-filter: blur(10px);
+}
+
+.arrow {
+  fill: rgba(0, 0, 0, 0.85);
+}
+```
+
+## API Reference
+
+### Provider
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `closeDelay` | `number` | — | Default close delay in ms for tooltips in this group. |
+| `delay` | `number` | — | Default open delay in ms for tooltips in this group. |
+| `timeout` | `number` | — | Duration in ms after a tooltip closes during which the next tooltip opens instantly. |
+
+### Root
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `align` | `'start' \| 'center' \| 'end'` | `'center'` | Alignment of the tooltip along the trigger's edge. |
+| `boundary` | `'viewport' \| 'container' \| string & {}` | — | Boundary used to constrain the tooltip position. |
+| `closeDelay` | `number` | `0` | Delay in ms before closing after pointer leaves. |
+| `defaultOpen` | `boolean` | `false` | Initial open state for uncontrolled usage. |
+| `delay` | `number` | `600` | Delay in ms before opening on hover. |
+| `disabled` | `boolean` | `false` | When true, the tooltip is disabled and will not open. |
+| `disableHoverablePopup` | `boolean` | `true` | When true, hovering the popup does not keep it open. |
+| `open` | `boolean` | `false` | Controlled open state. |
+| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | Preferred side of the trigger for the tooltip. |
+| `sticky` | `boolean` | `false` | Whether the tooltip stays open when another popup opens from its trigger. |
+
+#### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `transitionStarting` | `boolean` | Whether the open transition is in progress. |
+| `transitionEnding` | `boolean` | Whether the close transition is in progress. |
+| `open` | `boolean` | Whether the tooltip is currently visible. |
+| `status` | `'idle' \| 'starting' \| 'ending'` | Current phase of the transition lifecycle. |
+| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Preferred side of the trigger for the tooltip. |
+| `align` | `'start' \| 'center' \| 'end'` | How the tooltip is aligned relative to the specified side. |
+
+#### Data attributes
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-open` | — | Present when the tooltip is open. |
+| `data-side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Indicates the rendered side of the tooltip after collision handling. |
+| `data-align` | `'start' \| 'center' \| 'end'` | Indicates how the tooltip is aligned relative to the specified side. |
+
+#### CSS custom properties
+
+| Variable | Description |
+| --- | --- |
+| `--media-tooltip-side-offset` | Distance between the popup and the trigger along the side axis. |
+| `--media-tooltip-align-offset` | Distance between the popup and the trigger along the alignment axis. |
+| `--media-tooltip-boundary-offset` | Minimum distance between the popup and the positioning boundary. |
+| `--media-tooltip-anchor-width` | The anchor element's width. |
+| `--media-tooltip-anchor-height` | The anchor element's height. |
+| `--media-tooltip-available-width` | Available width between the trigger and the boundary edge. |
+| `--media-tooltip-available-height` | Available height between the trigger and the boundary edge. |
+
+### Trigger
+
+Element that triggers the tooltip on hover and focus. Renders a `<button>` element.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string \| ((state: TooltipState) => string \| undefined)` | — | Class name or function returning class name from state. |
+| `render` | `ReactElement \| ((props: HTMLProps, state: TooltipState) => ReactElement \| null)` | — | Render prop for custom element. |
+| `style` | `CSSProperties \| ((state: TooltipState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |
+
+#### Data attributes
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-open` | — | Present when the tooltip is open. |
+| `data-side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Indicates the rendered side of the tooltip after collision handling. |
+| `data-align` | `'start' \| 'center' \| 'end'` | Indicates how the tooltip is aligned relative to the specified side. |
+
+### Popup
+
+Container for the tooltip content. Positioned relative to the trigger using CSS anchor positioning with a JavaScript fallback.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string \| ((state: TooltipState) => string \| undefined)` | — | Class name or function returning class name from state. |
+| `render` | `ReactElement \| ((props: HTMLProps, state: TooltipState) => ReactElement \| null)` | — | Render prop for custom element. |
+| `style` | `CSSProperties \| ((state: TooltipState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |
+
+#### Data attributes
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-open` | — | Present when the tooltip is open. |
+| `data-side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Indicates the rendered side of the tooltip after collision handling. |
+| `data-align` | `'start' \| 'center' \| 'end'` | Indicates how the tooltip is aligned relative to the specified side. |
+
+### Label
+
+Tooltip body label; defaults to context `content.label` from the linked trigger.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string \| ((state: TooltipState) => string \| undefined)` | — | Class name or function returning class name from state. |
+| `render` | `ReactElement \| ((props: HTMLProps, state: TooltipState) => ReactElement \| null)` | — | Render prop for custom element. |
+| `style` | `CSSProperties \| ((state: TooltipState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |
+
+#### Data attributes
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-open` | — | Present when the tooltip is open. |
+| `data-side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Indicates the rendered side of the tooltip after collision handling. |
+| `data-align` | `'start' \| 'center' \| 'end'` | Indicates how the tooltip is aligned relative to the specified side. |
+
+### Shortcut
+
+Keyboard shortcut hint; apply skin `className` (CSS: `media-tooltip__kbd`; Tailwind: `popup.tooltipShortcut`).
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string \| ((state: TooltipState) => string \| undefined)` | — | Class name or function returning class name from state. |
+| `render` | `ReactElement \| ((props: HTMLProps, state: TooltipState) => ReactElement \| null)` | — | Render prop for custom element. |
+| `style` | `CSSProperties \| ((state: TooltipState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |
+
+#### Data attributes
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-open` | — | Present when the tooltip is open. |
+| `data-side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Indicates the rendered side of the tooltip after collision handling. |
+| `data-align` | `'start' \| 'center' \| 'end'` | Indicates how the tooltip is aligned relative to the specified side. |
+
+### Arrow
+
+Decorative arrow pointing from the tooltip toward the trigger. Hidden from assistive technology.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string \| ((state: TooltipState) => string \| undefined)` | — | Class name or function returning class name from state. |
+| `render` | `ReactElement \| ((props: HTMLProps, state: TooltipState) => ReactElement \| null)` | — | Render prop for custom element. |
+| `style` | `CSSProperties \| ((state: TooltipState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

package/docs/reference/components/twitch-video.md

@@ -0,0 +1,122 @@
+# TwitchVideo
+
+Video component that plays Twitch videos and live channels through the Twitch embed player
+
+The [Twitch embed player](https://dev.twitch.tv/docs/embed/video-and-clips/) handles both recorded videos and live channels. Its own chrome stays hidden by default, so it drops into a [player skin](../../guides/skins.md) like any other media component; set `controls` to use Twitch’s UI instead.
+
+## Import
+
+```bash
+pnpm add @videojs/twitch-video
+```
+
+```tsx
+import { TwitchVideo } from '@videojs/react/media/twitch-video';
+```
+
+## Load a source
+
+`src` takes a video URL (`twitch.tv/videos/<id>`) or a channel URL (`twitch.tv/<channel>`), with or without the `www.` and `go.` hosts. A channel URL plays the channel’s live stream. Clips (`clips.twitch.tv`) are a different embed and aren’t supported.
+
+```tsx
+<TwitchVideo src="https://www.twitch.tv/videos/106400740" />
+```
+
+## Live channels
+
+A channel embed behaves like a live media component:
+
+- `duration` reports `Infinity` while the stream is live.
+- Seeking is unavailable: the embed exposes no DVR window.
+- The stream going away and coming back dispatch `offline` and `online` events.
+- `loop` never repeats a channel; a live stream doesn’t end.
+
+## Parent hostnames
+
+Twitch checks the embedding page’s ancestors against a `parent` allowlist and won’t play unless the current page is on it. The element always includes your page’s own hostname, so a plain embed needs no setup. When your player is itself framed by other hostnames, name each of them under `engine.twitch.parent`:
+
+```tsx
+<TwitchVideo
+  source={{
+    src: 'https://www.twitch.tv/videos/106400740',
+    engine: { twitch: { parent: ['embed.example.com'] } },
+  }}
+/>
+```
+
+## Behavior
+
+- Volume and mute both work, like a native `<video>`.
+- `playbackRate` is reported but never applied: the embed has no rate command.
+- `loop` restarts a finished video from the top; the embed has no loop parameter.
+- `controls` is read when the embed is built; changing it later doesn’t take effect, since rebuilding the iframe would lose the playback session.
+- Fullscreen targets the iframe, so Twitch’s own chrome shows in fullscreen.
+
+## Examples
+
+### Basic Usage
+
+**App.tsx**
+
+```tsx
+import { TwitchVideo } from '@videojs/react/media/twitch-video';
+
+export default function BasicUsage() {
+  return (
+    <div className="twitch-video">
+      <TwitchVideo src="https://www.twitch.tv/videos/106400740" controls />
+    </div>
+  );
+}
+```
+
+**App.css**
+
+```css
+.twitch-video {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+```
+
+## API Reference
+
+### Props
+
+Accepts these Video.js-specific props:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `autoplay` | `boolean` | `false` | |
+| `controls` | `boolean` | `false` | |
+| `defaultMuted` | `boolean` | `false` | |
+| `loop` | `boolean` | `false` | |
+| `muted` | `boolean` | `false` | |
+| `playsInline` | `boolean` | `true` | |
+| `poster` | `string` | `''` | |
+| `preload` | `MediaPreloadType` | `'metadata'` | |
+| `source` | `{ src?: string; engine?: TwitchSourceEngineConfig } \| null` | `null` | Twitch VOD or channel URL in `src`, plus embed parameters under `engine.twitch`. Replacing it re-derives `src`. |
+| `src` | `string` | `''` | |
+
+### Engine options
+
+#### `source.engine.twitch`
+
+Pass [Twitch embed parameters](https://dev.twitch.tv/docs/embed/video-and-clips/) under `source.engine.twitch`, spelled exactly as Twitch spells them, plus anything Twitch adds next. [Media Sources](../../guides/media-sources.md) covers how engine options fit into a structured source.
+
+`controls`, `autoplay`, and `muted` come from the props of the same name, and the video or channel comes from `src`, so none of those have an `engine.twitch` spelling.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `collection` | `string \| undefined` | Collection to play through, starting from the video named by `src`. |
+| `parent` | `string \| readonly string[] \| undefined` | Every hostname the embed may be framed by. Twitch checks the frame's ancestors against it and refuses to play when the current page is missing, which is why the page's own hostname is always included on top of this. |
+| `referrerPolicy` | `ReferrerPolicy \| undefined` | `referrerpolicy` for the embed iframe. Not a Twitch embed parameter, so it never reaches the URL: the React player applies it to the iframe it renders, and the HTML player reads its own `referrerpolicy` attribute instead. |
+| `time` | `string \| undefined` | Start position, spelled the way Twitch spells timestamps: `1h30m10s`. |
+
+### Ref
+
+Forwards its ref to the rendered `<iframe>`. The ref is an [HTMLIFrameElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement). Control playback with the component props and player APIs rather than the iframe ref.
+
+### Events
+
+Handle standard media events with React event props such as `onPlay` and `onTimeUpdate`. For native events without a React prop, attach a listener through the ref with `addEventListener`.

package/docs/reference/components/video-minimal-skin.md

@@ -0,0 +1,46 @@
+# MinimalVideoSkin
+
+The video preset's visually lighter skin, closer to a classic control bar
+
+The minimal skin of the video preset: the same player and the same controls in a visually lighter design, closer to a classic control bar. The [default video skin](./video-skin.md) is the same preset’s other variant. See [Skins](../../guides/skins.md) for how packaged skins work and [Presets](../../guides/presets.md) for what the video preset ships.
+
+## Import
+
+```tsx
+import { MinimalVideoSkin } from '@videojs/react/video';
+import '@videojs/react/video/minimal-skin.css';
+```
+
+## Usage
+
+The skin goes between the player and the media element. It renders its controls around the media.
+
+```tsx
+<VideoPlayer>
+  <MinimalVideoSkin>
+    <Video src="video.mp4" />
+  </MinimalVideoSkin>
+</VideoPlayer>
+```
+
+## Poster
+
+The skin renders a poster image before playback starts. Pass `renderPoster` to replace it with your own component.
+
+See [Add a poster and loading placeholder](../../guides/poster.md) for complete examples.
+
+## Thumbnail
+
+The skin renders a storyboard preview image while scrubbing the time slider. Pass `renderThumbnail` to replace it with your own image, for example to set `crossOrigin`, `loading`, or `fetchPriority`.
+
+See [Show timeline thumbnail previews](../../guides/thumbnails.md) for complete examples.
+
+## Styling
+
+Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](../../guides/customize-skins.md#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.
+
+## Own the UI
+
+Packaged skins keep their controls and layout inside Video.js. When you need to add, remove, rearrange, or deeply restyle controls, use Shadcn to add the skin source to your project. Its components, layout, styles, and interactions become local files you can change.
+
+- [Install Video.js with Shadcn](../../guides/installation-shadcn.md): Add editable skin source and build a working React or HTML player

package/docs/reference/components/video-skin.md

@@ -0,0 +1,46 @@
+# VideoSkin
+
+The video preset's default skin with the modern, frosted look
+
+The default skin of the video preset: the control layout for on-demand video with the modern, frosted look. [MinimalVideoSkin](./video-minimal-skin.md) is the same preset’s other variant. See [Skins](../../guides/skins.md) for how packaged skins work and [Presets](../../guides/presets.md) for what the video preset ships.
+
+## Import
+
+```tsx
+import { VideoSkin } from '@videojs/react/video';
+import '@videojs/react/video/skin.css';
+```
+
+## Usage
+
+The skin goes between the player and the media element. It renders its controls around the media.
+
+```tsx
+<VideoPlayer>
+  <VideoSkin>
+    <Video src="video.mp4" />
+  </VideoSkin>
+</VideoPlayer>
+```
+
+## Poster
+
+The skin renders a poster image before playback starts. Pass `renderPoster` to replace it with your own component.
+
+See [Add a poster and loading placeholder](../../guides/poster.md) for complete examples.
+
+## Thumbnail
+
+The skin renders a storyboard preview image while scrubbing the time slider. Pass `renderThumbnail` to replace it with your own image, for example to set `crossOrigin`, `loading`, or `fetchPriority`.
+
+See [Show timeline thumbnail previews](../../guides/thumbnails.md) for complete examples.
+
+## Styling
+
+Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](../../guides/customize-skins.md#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.
+
+## Own the UI
+
+Packaged skins keep their controls and layout inside Video.js. When you need to add, remove, rearrange, or deeply restyle controls, use Shadcn to add the skin source to your project. Its components, layout, styles, and interactions become local files you can change.
+
+- [Install Video.js with Shadcn](../../guides/installation-shadcn.md): Add editable skin source and build a working React or HTML player

package/docs/reference/components/video.md

@@ -0,0 +1,79 @@
+# Video
+
+Native video playback that can provide media to a Video.js player
+
+## Import
+
+Import `Video` from the video preset:
+
+```tsx
+import { Video } from '@videojs/react/video';
+```
+
+## Anatomy
+
+```tsx
+<Video>
+  <source />
+  <track />
+</Video>
+```
+
+## Use with a player
+
+Place `Video` anywhere inside a `VideoPlayer`, or inside another Video.js `Player` configured for video. It becomes that player’s media provider automatically. Outside a player, `Video` behaves as a standalone native `<video>`.
+
+## Native behavior
+
+Video.js does not replace the native video API. Use `src` for one URL or add child [`<source>` elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/source) when the browser should choose between candidates. See [Media sources](../../guides/media-sources.md) when you need an HLS, DASH, Mux, or other playback adapter.
+
+Add native [`<track>` elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/track) for captions, subtitles, chapters, descriptions, or metadata.
+
+`Video` forwards native attributes, event handlers, and children to the underlying `<video>`. Its `ref` resolves to the `HTMLVideoElement`.
+
+See MDN for the complete [`<video>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/video), [`HTMLVideoElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement), and shared [`HTMLMediaElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement) APIs.
+
+## Examples
+
+### Basic Usage
+
+This native video uses a child source, captions track, and browser controls while also providing media to the surrounding Video.js player.
+
+**App.tsx**
+
+```tsx
+import { Container } from '@videojs/react';
+import { Video, VideoPlayer } from '@videojs/react/video';
+
+import './BasicUsage.css';
+
+export default function BasicUsage() {
+  return (
+    <VideoPlayer>
+      <Container className="react-video-basic">
+        <Video className="react-video-basic__media" controls playsInline preload="metadata">
+          <source src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" type="video/mp4" />
+          <track kind="captions" src="/docs/demos/captions-button/captions.vtt" srcLang="en" label="English" />
+        </Video>
+      </Container>
+    </VideoPlayer>
+  );
+}
+```
+
+**App.css**
+
+```css
+.react-video-basic {
+  width: 100%;
+  overflow: hidden;
+  background: black;
+  border-radius: 8px;
+}
+
+.react-video-basic__media {
+  display: block;
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+```