diff --git a/packages/core/src/dom/index.ts b/packages/core/src/dom/index.ts
index 1b4e4de3..9a22a97d 100644
--- a/packages/core/src/dom/index.ts
+++ b/packages/core/src/dom/index.ts
@@ -8,6 +8,7 @@ export * from './hotkey/aria';
 export * from './hotkey/coordinator';
 export * from './hotkey/hotkey';
 export * from './hotkey/hotkey-events';
+export * from './media/predicate';
 export * from './media/types';
 export * from './store/features';
 export * from './store/selectors';
diff --git a/site/src/components/docs/demos/use-media/react/css/BasicUsage.css b/site/src/components/docs/demos/use-media/react/css/BasicUsage.css
new file mode 100644
index 00000000..6816b120
--- /dev/null
+++ b/site/src/components/docs/demos/use-media/react/css/BasicUsage.css
@@ -0,0 +1,36 @@
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.info-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 12px;
+  margin: 0;
+  font-size: 0.8125rem;
+  background: rgba(0, 0, 0, 0.05);
+  border-top: 1px solid rgba(0, 0, 0, 0.1);
+}
+
+.info-panel div {
+  display: flex;
+  gap: 8px;
+}
+
+.info-panel dt {
+  min-width: 80px;
+  color: #6b7280;
+}
+
+.info-panel dd {
+  margin: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+}
diff --git a/site/src/components/docs/demos/use-media/react/css/BasicUsage.tsx b/site/src/components/docs/demos/use-media/react/css/BasicUsage.tsx
new file mode 100644
index 00000000..d4522ea3
--- /dev/null
+++ b/site/src/components/docs/demos/use-media/react/css/BasicUsage.tsx
@@ -0,0 +1,52 @@
+import { createPlayer, isMediaSourceCapable, isMediaVideoDimensionsCapable } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({
+  features: videoFeatures,
+});
+
+function MediaInfo() {
+  const media = Player.useMedia();
+
+  if (!media) return null;
+
+  return (
+    <dl className="info-panel">
+      {isMediaSourceCapable(media) && (
+        <div>
+          <dt>src</dt>
+          <dd>{media.currentSrc || '—'}</dd>
+        </div>
+      )}
+      {isMediaVideoDimensionsCapable(media) && (
+        <>
+          <div>
+            <dt>videoWidth</dt>
+            <dd>{media.videoWidth}px</dd>
+          </div>
+          <div>
+            <dt>videoHeight</dt>
+            <dd>{media.videoHeight}px</dd>
+          </div>
+        </>
+      )}
+    </dl>
+  );
+}
+
+export default function BasicUsage() {
+  return (
+    <Player.Provider>
+      <Player.Container className="media-container">
+        <Video
+          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
+          autoPlay
+          muted
+          playsInline
+          loop
+        />
+        <MediaInfo />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
diff --git a/site/src/content/docs/reference/use-media.mdx b/site/src/content/docs/reference/use-media.mdx
index 70b0c747..0c354f5b 100644
--- a/site/src/content/docs/reference/use-media.mdx
+++ b/site/src/content/docs/reference/use-media.mdx
@@ -1,11 +1,34 @@
 ---
 title: Player.useMedia
-description: Hook to access the underlying media element from within a Player.Provider
+description: Hook to access the media object from within a Player.Provider
 ---
 
 import UtilReference from "@/components/docs/api-reference/UtilReference.astro";
+import Demo from "@/components/docs/demos/Demo.astro";
 import DocsLink from "@/components/docs/DocsLink.astro";
+import FrameworkCase from "@/components/docs/FrameworkCase.astro";
+import StyleCase from "@/components/docs/StyleCase.astro";
+import BasicUsageDemoReact from "@/components/docs/demos/use-media/react/css/BasicUsage";
+import basicUsageReactTsx from "@/components/docs/demos/use-media/react/css/BasicUsage.tsx?raw";
+import basicUsageReactCss from "@/components/docs/demos/use-media/react/css/BasicUsage.css?raw";
 
-`Player.useMedia` returns the current `HTMLMediaElement` (or `null` if no media element has been registered yet). Use it to interact directly with the native media element when needed. It must be called within a `Player.Provider`. The media element becomes available after a `<Video>` or `<Audio>` component mounts inside the provider tree. Also available as a standalone import (`import { useMedia } from '@videojs/react'`) — identical behavior, no typing difference. To attach a custom media element instead of the built-in components, see <DocsLink slug="reference/use-media-attach">`useMediaAttach`</DocsLink>.
+`Player.useMedia` (from <DocsLink slug="reference/create-player">`createPlayer`</DocsLink>) returns the current `Media` object (or `null` if no media has been registered yet). `Media` is a runtime-agnostic playback interface — any instance that conforms to it, including an `HTMLVideoElement`, can be the media. It exposes capabilities like `play()` and event subscription rather than assuming a native element. It must be called within a `Player.Provider`. The media object becomes available after a `<Video>` or `<Audio>` component mounts inside the provider tree. To attach a custom media element instead of the built-in components, see <DocsLink slug="reference/use-media-attach">`useMediaAttach`</DocsLink>.
+
+## Examples
+
+### Basic Usage
+
+<FrameworkCase frameworks={["react"]}>
+  <StyleCase styles={["css"]}>
+    <Demo
+      files={[
+        { title: "App.tsx", code: basicUsageReactTsx, lang: "tsx" },
+        { title: "App.css", code: basicUsageReactCss, lang: "css" },
+      ]}
+    >
+      <BasicUsageDemoReact client:idle />
+    </Demo>
+  </StyleCase>
+</FrameworkCase>
 
 <UtilReference util="useMedia" />