From 84b7b0774a1fb655f4cb7f6a87e589097a661685 Mon Sep 17 00:00:00 2001
From: Darius Cepulis <dcepulis@mux.com>
Date: Fri, 13 Feb 2026 09:24:04 -0600
Subject: [PATCH] feat(site): add buffering indicator api reference

closes #532
closes #533
---
 .../buffering-indicator.tsx                   |  1 +
 .../html/css/BasicUsage.astro                 | 10 +++
 .../html/css/BasicUsage.css                   | 39 +++++++++++
 .../html/css/BasicUsage.html                  | 12 ++++
 .../html/css/BasicUsage.ts                    |  2 +
 .../react/css/BasicUsage.css                  | 39 +++++++++++
 .../react/css/BasicUsage.tsx                  | 27 ++++++++
 .../docs/reference/buffering-indicator.mdx    | 65 +++++++++++++++++++
 site/src/docs.config.ts                       |  1 +
 9 files changed, 196 insertions(+)
 create mode 100644 site/src/components/docs/demos/buffering-indicator/html/css/BasicUsage.astro
 create mode 100644 site/src/components/docs/demos/buffering-indicator/html/css/BasicUsage.css
 create mode 100644 site/src/components/docs/demos/buffering-indicator/html/css/BasicUsage.html
 create mode 100644 site/src/components/docs/demos/buffering-indicator/html/css/BasicUsage.ts
 create mode 100644 site/src/components/docs/demos/buffering-indicator/react/css/BasicUsage.css
 create mode 100644 site/src/components/docs/demos/buffering-indicator/react/css/BasicUsage.tsx
 create mode 100644 site/src/content/docs/reference/buffering-indicator.mdx

diff --git a/packages/react/src/ui/buffering-indicator/buffering-indicator.tsx b/packages/react/src/ui/buffering-indicator/buffering-indicator.tsx
index c826baa2..6708c014 100644
--- a/packages/react/src/ui/buffering-indicator/buffering-indicator.tsx
+++ b/packages/react/src/ui/buffering-indicator/buffering-indicator.tsx
@@ -46,6 +46,7 @@ export const BufferingIndicator = forwardRef(function BufferingIndicator(
 
   const state = useSyncExternalStore(
     (cb) => core.state.subscribe(cb),
+    () => core.state.current,
     () => core.state.current
   );
 
diff --git a/site/src/components/docs/demos/buffering-indicator/html/css/BasicUsage.astro b/site/src/components/docs/demos/buffering-indicator/html/css/BasicUsage.astro
new file mode 100644
index 00000000..e7e95f49
--- /dev/null
+++ b/site/src/components/docs/demos/buffering-indicator/html/css/BasicUsage.astro
@@ -0,0 +1,10 @@
+---
+import HtmlDemo from '@/components/docs/demos/HtmlDemo.astro';
+import html from './BasicUsage.html?raw';
+import './BasicUsage.css';
+---
+
+<HtmlDemo html={html} />
+<script>
+  import './BasicUsage.ts';
+</script>
diff --git a/site/src/components/docs/demos/buffering-indicator/html/css/BasicUsage.css b/site/src/components/docs/demos/buffering-indicator/html/css/BasicUsage.css
new file mode 100644
index 00000000..da2236a6
--- /dev/null
+++ b/site/src/components/docs/demos/buffering-indicator/html/css/BasicUsage.css
@@ -0,0 +1,39 @@
+.buffering-indicator-basic {
+  display: flex;
+  width: 100%;
+  height: 100%;
+  position: relative;
+}
+
+.buffering-indicator-basic__overlay {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  pointer-events: none;
+  z-index: 30;
+}
+
+.buffering-indicator-basic__overlay .buffering-indicator-basic__spinner {
+  display: none;
+}
+
+.buffering-indicator-basic__overlay[data-visible] .buffering-indicator-basic__spinner {
+  display: block;
+}
+
+.buffering-indicator-basic__spinner {
+  width: 48px;
+  height: 48px;
+  border: 4px solid rgba(255, 255, 255, 0.3);
+  border-top-color: white;
+  border-radius: 50%;
+  animation: buffering-spin 0.8s linear infinite;
+}
+
+@keyframes buffering-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
diff --git a/site/src/components/docs/demos/buffering-indicator/html/css/BasicUsage.html b/site/src/components/docs/demos/buffering-indicator/html/css/BasicUsage.html
new file mode 100644
index 00000000..3e8e7265
--- /dev/null
+++ b/site/src/components/docs/demos/buffering-indicator/html/css/BasicUsage.html
@@ -0,0 +1,12 @@
+<video-player class="buffering-indicator-basic">
+    <video
+        src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
+        autoplay
+        muted
+        playsinline
+        loop
+    ></video>
+    <media-buffering-indicator class="buffering-indicator-basic__overlay">
+        <div class="buffering-indicator-basic__spinner"></div>
+    </media-buffering-indicator>
+</video-player>
diff --git a/site/src/components/docs/demos/buffering-indicator/html/css/BasicUsage.ts b/site/src/components/docs/demos/buffering-indicator/html/css/BasicUsage.ts
new file mode 100644
index 00000000..c28dcd98
--- /dev/null
+++ b/site/src/components/docs/demos/buffering-indicator/html/css/BasicUsage.ts
@@ -0,0 +1,2 @@
+import '@videojs/html/video/player';
+import '@videojs/html/ui/buffering-indicator';
diff --git a/site/src/components/docs/demos/buffering-indicator/react/css/BasicUsage.css b/site/src/components/docs/demos/buffering-indicator/react/css/BasicUsage.css
new file mode 100644
index 00000000..da2236a6
--- /dev/null
+++ b/site/src/components/docs/demos/buffering-indicator/react/css/BasicUsage.css
@@ -0,0 +1,39 @@
+.buffering-indicator-basic {
+  display: flex;
+  width: 100%;
+  height: 100%;
+  position: relative;
+}
+
+.buffering-indicator-basic__overlay {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  pointer-events: none;
+  z-index: 30;
+}
+
+.buffering-indicator-basic__overlay .buffering-indicator-basic__spinner {
+  display: none;
+}
+
+.buffering-indicator-basic__overlay[data-visible] .buffering-indicator-basic__spinner {
+  display: block;
+}
+
+.buffering-indicator-basic__spinner {
+  width: 48px;
+  height: 48px;
+  border: 4px solid rgba(255, 255, 255, 0.3);
+  border-top-color: white;
+  border-radius: 50%;
+  animation: buffering-spin 0.8s linear infinite;
+}
+
+@keyframes buffering-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
diff --git a/site/src/components/docs/demos/buffering-indicator/react/css/BasicUsage.tsx b/site/src/components/docs/demos/buffering-indicator/react/css/BasicUsage.tsx
new file mode 100644
index 00000000..bd0baba9
--- /dev/null
+++ b/site/src/components/docs/demos/buffering-indicator/react/css/BasicUsage.tsx
@@ -0,0 +1,27 @@
+import { BufferingIndicator, createPlayer, features, Video } from '@videojs/react';
+
+import './BasicUsage.css';
+
+const Player = createPlayer({ features: [...features.video] });
+
+export default function BasicUsage() {
+  return (
+    <Player.Provider>
+      <Player.Container className="buffering-indicator-basic">
+        <Video
+          src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
+          autoPlay
+          muted
+          playsInline
+          loop
+        />
+        <BufferingIndicator
+          className="buffering-indicator-basic__overlay"
+          render={(props, state) => (
+            <div {...props}>{state.visible && <div className="buffering-indicator-basic__spinner" />}</div>
+          )}
+        />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
diff --git a/site/src/content/docs/reference/buffering-indicator.mdx b/site/src/content/docs/reference/buffering-indicator.mdx
new file mode 100644
index 00000000..e36945c5
--- /dev/null
+++ b/site/src/content/docs/reference/buffering-indicator.mdx
@@ -0,0 +1,65 @@
+---
+title: BufferingIndicator
+frameworkTitle:
+  html: media-buffering-indicator
+description: A component that displays a loading indicator when media is buffering
+---
+
+import ApiReference from "@/components/docs/api-reference/ApiReference.astro";
+import FrameworkCase from "@/components/docs/FrameworkCase.astro";
+import StyleCase from "@/components/docs/StyleCase.astro";
+import Demo from "@/components/docs/demos/Demo.astro";
+
+{/* React demos */}
+import BasicUsageDemoReact from "@/components/docs/demos/buffering-indicator/react/css/BasicUsage";
+import basicUsageReactTsx from "@/components/docs/demos/buffering-indicator/react/css/BasicUsage.tsx?raw";
+import basicUsageReactCss from "@/components/docs/demos/buffering-indicator/react/css/BasicUsage.css?raw";
+
+{/* HTML demos */}
+import BasicUsageDemoHtml from "@/components/docs/demos/buffering-indicator/html/css/BasicUsage.astro";
+import basicUsageHtml from "@/components/docs/demos/buffering-indicator/html/css/BasicUsage.html?raw";
+import basicUsageHtmlCss from "@/components/docs/demos/buffering-indicator/html/css/BasicUsage.css?raw";
+import basicUsageHtmlTs from "@/components/docs/demos/buffering-indicator/html/css/BasicUsage.ts?raw";
+
+## Anatomy
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+<BufferingIndicator />
+```
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+```html
+<media-buffering-indicator></media-buffering-indicator>
+```
+</FrameworkCase>
+
+## 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>
+
+<FrameworkCase frameworks={["html"]}>
+  <StyleCase styles={["css"]}>
+    <Demo files={[
+      { title: "index.html", code: basicUsageHtml, lang: "html" },
+      { title: "index.css", code: basicUsageHtmlCss, lang: "css" },
+      { title: "index.ts", code: basicUsageHtmlTs, lang: "ts" },
+    ]}>
+      <BasicUsageDemoHtml />
+    </Demo>
+  </StyleCase>
+</FrameworkCase>
+
+<ApiReference component="BufferingIndicator" />
diff --git a/site/src/docs.config.ts b/site/src/docs.config.ts
index 024ffe2b..d69e2065 100644
--- a/site/src/docs.config.ts
+++ b/site/src/docs.config.ts
@@ -25,6 +25,7 @@ export const sidebar: Sidebar = [
     sidebarLabel: 'Components',
     contents: [
       // sorted alphabetically
+      { slug: 'reference/buffering-indicator' },
       { slug: 'reference/controls' },
       { slug: 'reference/fullscreen-button' },
       { slug: 'reference/mute-button' },