THEOplayer · ceyhun-o · Aug 6, 2026 · Aug 6, 2026 · Aug 6, 2026 · Aug 6, 2026
diff --git a/docs/components/Example.tsx b/docs/components/Example.tsx
@@ -8,10 +8,12 @@ export interface Controller {
 export interface Props extends ComponentPropsWithoutRef<'iframe'> {
     hideSource?: boolean;
     hideDeviceType?: boolean;
+    // This is for the language selector on the Localization example.
+    languages?: Record<string, string>;
     ref?: Ref<Controller> | undefined;
 }
 
-export default function Example({ hideSource, hideDeviceType, ref, ...props }: Props): JSX.Element {
+export default function Example({ hideSource, hideDeviceType, languages, ref, ...props }: Props): JSX.Element {
     const iframeRef = useRef<HTMLIFrameElement | null>(null);
     useImperativeHandle(ref, () => {
         return {
@@ -23,6 +25,16 @@ export default function Example({ hideSource, hideDeviceType, ref, ...props }: P
 
     const [sourceName, setSourceName] = useState<SourceName>('bigBuckBunny');
     const [deviceType, setDeviceType] = useState('');
+    const [language, setLanguage] = useState(languages ? Object.keys(languages)[0] : '');
+
+    // Send message to <iframe> when language changes
+    useEffect(() => {
+        if (!languages) return;
+        iframeRef.current?.contentWindow?.postMessage({
+            type: 'language',
+            language: language
+        });
+    }, [iframeRef.current, language, languages]);
 
     // Send message to <iframe> when source changes
     useEffect(() => {
@@ -42,12 +54,26 @@ export default function Example({ hideSource, hideDeviceType, ref, ...props }: P
         });
     }, [iframeRef.current, deviceType, hideDeviceType]);
 
-    const showOptions = !hideSource || !hideDeviceType;
+    const showOptions = !hideSource || !hideDeviceType || !!languages;
     return (
         <>
             <iframe ref={iframeRef} {...props}></iframe>
             {showOptions && (
-                <p>
+                <div>
+                    {languages && (
+                        <div>
+                            <label style={{ userSelect: 'none' }}>
+                                Language:{' '}
+                                <select value={language} onChange={(e) => setLanguage(e.target.value)}>
+                                    {Object.entries(languages).map(([value, label]) => (
+                                        <option key={value} value={value}>
+                                            {label}
+                                        </option>
+                                    ))}
+                                </select>
+                            </label>
+                        </div>
+                    )}
                     {!hideSource && (
                         <div>
                             <label style={{ userSelect: 'none' }}>
@@ -75,7 +101,7 @@ export default function Example({ hideSource, hideDeviceType, ref, ...props }: P
                             </label>
                         </div>
                     )}
-                </p>
+                </div>
             )}
         </>
     );

diff --git a/docs/examples/custom-ui/_category_.json b/docs/examples/custom-ui/_category_.json
@@ -0,0 +1,7 @@
+{
+  "label": "Custom UI",
+  "position": 20,
+  "collapsible": true,
+  "collapsed": true,
+  "description": "Samples demonstrating how to implement a custom UI and modify different components."
+}
diff --git a/docs/examples/custom-ui/custom-play-button.mdx b/docs/examples/custom-ui/custom-play-button.mdx
@@ -0,0 +1,71 @@
+---
+sidebar_position: 6
+sidebar_custom_props: { 'icon': '⏯️' }
+slug: /web/examples/custom-play-button
+---
+
+# Custom play button
+
+import Example from '../../components/Example';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import styles from '../shared.module.css';
+
+<Example className={styles.player} src={useBaseUrl('/open-video-ui/v2/examples/web/custom-play-button/demo.html')} hideDeviceType />
+
+This sample demonstrates a custom, animated play button.
+
+<details>
+    <summary>Code</summary>
+    ```html showLineNumbers
+    <style>
+        .big-play {
+            color: #fff;
+            background: rgba(124, 58, 237, 0.45);
+            backdrop-filter: blur(6px);
+            border-radius: 50%;
+            padding: 32px;
+            transition: transform 0.4s ease;
+        }
+        .big-play svg {
+            width: 64px;
+            height: 64px;
+        }
+        /* Only pulse while hovered. */
+        .big-play:hover {
+            animation: pulse 3s ease-in-out infinite;
+        }
+        @keyframes pulse {
+            0%, 100% { transform: scale(1); }
+            50% { transform: scale(1.06); }
+        }
+    </style>
+
+    <theoplayer-ui
+        configuration='{"libraryLocation":"/path/to/theoplayer/","license":"your_theoplayer_license"}'
+        source='{"sources":{"src":"https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8"}}'
+    >
+        <div slot="centered-chrome">
+            <theoplayer-play-button class="big-play">
+                <svg slot="play-icon" viewBox="0 0 24 24" width="28" height="28" fill="currentColor"><path d="M8 5v14l11-7z"></path></svg>
+                <svg slot="pause-icon" viewBox="0 0 24 24" width="28" height="28" fill="currentColor"><path d="M6 5h4v14H6zM14 5h4v14h-4z"></path></svg>
+            </theoplayer-play-button>
+        </div>
+        <div class="bottom-chrome">
+            <theoplayer-control-bar>
+                <theoplayer-time-range></theoplayer-time-range>
+            </theoplayer-control-bar>
+            <theoplayer-control-bar>
+                <theoplayer-play-button></theoplayer-play-button>
+                <theoplayer-mute-button></theoplayer-mute-button>
+                <theoplayer-volume-range></theoplayer-volume-range>
+                <theoplayer-time-display show-duration></theoplayer-time-display>
+                <theoplayer-fullscreen-button></theoplayer-fullscreen-button>
+            </theoplayer-control-bar>
+        </div>
+        <theoplayer-error-display slot="error"></theoplayer-error-display>
+    </theoplayer-ui>
+    ```
+
+    [📜 View full source on GitHub](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/examples/web/custom-play-button/demo.html)
+
+</details>
diff --git a/docs/examples/custom-ui.mdx → docs/examples/custom-ui/example.mdx b/docs/examples/custom-ui.mdx → docs/examples/custom-ui/example.mdx
@@ -1,16 +1,20 @@
 ---
-sidebar_position: 20
+sidebar_position: 1
 sidebar_custom_props: { 'icon': '▶️' }
+slug: /web/examples/custom-ui
+sidebar_label: Custom styling
 ---
 
 # Custom UI
 
-import Example from '../components/Example';
+import Example from '../../components/Example';
 import useBaseUrl from '@docusaurus/useBaseUrl';
-import styles from './shared.module.css';
+import styles from '../shared.module.css';
 
 <Example className={styles.player} src={useBaseUrl('/open-video-ui/v2/examples/web/custom-ui/demo.html')}></Example>
 
+This sample demonstrates a basic custom UI.
+
 <details>
     <summary>Code</summary>
     ```html showLineNumbers

diff --git a/docs/examples/custom-ui/modern.mdx b/docs/examples/custom-ui/modern.mdx
@@ -0,0 +1,58 @@
+---
+sidebar_position: 5
+sidebar_custom_props: { 'icon': '✨' }
+slug: /web/examples/modern
+---
+
+# Modern UI
+
+import Example from '../../components/Example';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import styles from '../shared.module.css';
+
+<Example className={styles.player} src={useBaseUrl('/open-video-ui/v2/examples/web/modern/demo.html')} hideDeviceType />
+
+This sample demonstrates a modern, streaming-service style custom UI: a centered playback "pill" with rewind, play/pause and forward, a full-width seek bar, and rounded translucent control clusters.
+
+<details>
+    <summary>Code</summary>
+    ```html showLineNumbers
+    <theoplayer-ui
+        configuration='{"libraryLocation":"/path/to/theoplayer/","license":"your_theoplayer_license"}'
+        source='{"sources":{"src":"https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny.m3u8"},"metadata":{"title":"Big Buck Bunny"}}'
+    >
+        <div slot="centered-chrome">
+            <div class="pill center-pill">
+                <theoplayer-seek-button seek-offset="-10"></theoplayer-seek-button>
+                <theoplayer-play-button></theoplayer-play-button>
+                <theoplayer-seek-button seek-offset="10"></theoplayer-seek-button>
+            </div>
+        </div>
+        <div class="bottom-chrome">
+            <theoplayer-control-bar>
+                <theoplayer-time-range></theoplayer-time-range>
+            </theoplayer-control-bar>
+            <div class="bottom-row">
+                <span class="pill">
+                    <theoplayer-play-button></theoplayer-play-button>
+                    <span class="volume">
+                        <theoplayer-mute-button></theoplayer-mute-button>
+                        <theoplayer-volume-range></theoplayer-volume-range>
+                    </span>
+                    <theoplayer-time-display show-duration></theoplayer-time-display>
+                </span>
+                <span class="spacer"></span>
+                <span class="pill">
+                    <theoplayer-language-menu-button menu="language-menu"></theoplayer-language-menu-button>
+                    <theoplayer-fullscreen-button></theoplayer-fullscreen-button>
+                </span>
+            </div>
+        </div>
+        <theoplayer-language-menu id="language-menu" slot="menu" hidden></theoplayer-language-menu>
+        <theoplayer-error-display slot="error"></theoplayer-error-display>
+    </theoplayer-ui>
+    ```
+
+    [📜 View full source on GitHub](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/examples/web/modern/demo.html)
+
+</details>
diff --git a/docs/examples/nitflex.mdx → docs/examples/custom-ui/nitflex.mdx b/docs/examples/nitflex.mdx → docs/examples/custom-ui/nitflex.mdx
@@ -1,13 +1,15 @@
 ---
-sidebar_position: 22
+sidebar_position: 2
 sidebar_custom_props: { 'icon': '📺' }
+slug: /web/examples/nitflex
+sidebar_label: Nitflex theme
 ---
 
 # Custom UI: Nitflex theme
 
-import Example from '../components/Example';
+import Example from '../../components/Example';
 import useBaseUrl from '@docusaurus/useBaseUrl';
-import styles from './shared.module.css';
+import styles from '../shared.module.css';
 
 <Example className={styles.player} hideDeviceType src={useBaseUrl('/open-video-ui/v2/examples/web/nitflex/demo.html')}></Example>
 

diff --git a/docs/examples/portrait.mdx → docs/examples/custom-ui/portrait.mdx b/docs/examples/portrait.mdx → docs/examples/custom-ui/portrait.mdx
@@ -1,13 +1,15 @@
 ---
-sidebar_position: 21
+sidebar_position: 3
 sidebar_custom_props: { 'icon': '📱' }
+slug: /web/examples/portrait
+sidebar_label: Portrait theme
 ---
 
 # Custom UI: Portrait theme
 
-import Example from '../components/Example';
+import Example from '../../components/Example';
 import useBaseUrl from '@docusaurus/useBaseUrl';
-import styles from './shared.module.css';
+import styles from '../shared.module.css';
 
 <Example className={styles.portraitPlayer} hideSource hideDeviceType src={useBaseUrl('/open-video-ui/v2/examples/web/portrait/demo.html')}></Example>
 

diff --git a/docs/examples/custom-ui/text-tracks.mdx b/docs/examples/custom-ui/text-tracks.mdx
@@ -0,0 +1,81 @@
+---
+sidebar_position: 4
+sidebar_custom_props: { 'icon': '💬' }
+slug: /web/examples/text-tracks
+---
+
+# Text tracks and subtitles
+
+import Example from '../../components/Example';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import styles from '../shared.module.css';
+
+<Example className={styles.player} src={useBaseUrl('/open-video-ui/v2/examples/web/text-tracks/demo.html')} hideSource hideDeviceType />
+
+This example demonstrates the text track components for subtitle selection and styling.
+
+The settings menu contains four submenus:
+
+- **Subtitles**: the idiomatic `<theoplayer-track-radio-group track-type="subtitles" show-off>`, which composes `<theoplayer-text-track-off-radio-button>` and `<theoplayer-text-track-radio-button>` for you.
+- **Subtitles (custom)**: the same picker built manually from `<theoplayer-text-track-off-radio-button>` and `<theoplayer-text-track-radio-button>`.
+- **Subtitle appearance**: the pre-built `<theoplayer-text-track-style-menu>`, which composes `<theoplayer-text-track-style-display>`, `<theoplayer-text-track-style-radio-group>` and `<theoplayer-text-track-style-reset-button>`.
+- **Font color (custom)**: a single style option built manually from `<theoplayer-text-track-style-radio-group>` and `<theoplayer-text-track-style-reset-button>`.
+
+<details>
+    <summary>Code</summary>
+    ```html showLineNumbers
+    <theoplayer-ui
+        configuration='{"libraryLocation":"/path/to/theoplayer/","license":"your_theoplayer_license"}'
+        source='{"sources":{"src":"https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8"},"metadata":{"title":"Elephant&apos;s Dream"}}'
+    >
+        <theoplayer-control-bar>
+            <theoplayer-play-button></theoplayer-play-button>
+            <theoplayer-mute-button></theoplayer-mute-button>
+            <theoplayer-volume-range></theoplayer-volume-range>
+            <theoplayer-time-display show-duration></theoplayer-time-display>
+            <theoplayer-language-menu-button menu="language-menu"></theoplayer-language-menu-button>
+            <theoplayer-menu-button menu="settings-menu">CC</theoplayer-menu-button>
+            <theoplayer-fullscreen-button></theoplayer-fullscreen-button>
+        </theoplayer-control-bar>
+
+        <theoplayer-language-menu id="language-menu" slot="menu" hidden></theoplayer-language-menu>
+
+        <theoplayer-menu-group id="settings-menu" slot="menu" hidden>
+            <theoplayer-menu>
+                <span slot="heading">Subtitles &amp; captions</span>
+                <theoplayer-menu-button menu="subtitle-menu"><span>Select</span></theoplayer-menu-button>
+                <theoplayer-menu-button menu="subtitle-style-menu">
+                    <theoplayer-text-track-style-display property="fontColor"></theoplayer-text-track-style-display>
+                </theoplayer-menu-button>
+            </theoplayer-menu>
+
+            <!-- Idiomatic subtitle picker (composes TextTrackOffRadioButton + TextTrackRadioButton). -->
+            <theoplayer-menu id="subtitle-menu" menu-close-on-input hidden>
+                <span slot="heading">Subtitles</span>
+                <theoplayer-track-radio-group track-type="subtitles" show-off></theoplayer-track-radio-group>
+            </theoplayer-menu>
+
+            <!-- Pre-built subtitle style menu. -->
+            <theoplayer-text-track-style-menu id="subtitle-style-menu" menu-close-on-input hidden>
+                <span slot="heading">Subtitle appearance</span>
+            </theoplayer-text-track-style-menu>
+
+            <!-- Manual font color submenu (TextTrackStyleRadioGroup + TextTrackStyleResetButton). -->
+            <theoplayer-menu id="font-color-menu" menu-close-on-input hidden>
+                <theoplayer-text-track-style-reset-button slot="heading"></theoplayer-text-track-style-reset-button>
+                <span slot="heading">Font color (custom)</span>
+                <theoplayer-text-track-style-radio-group property="fontColor">
+                    <theoplayer-radio-button value="">Default</theoplayer-radio-button>
+                    <theoplayer-radio-button value="rgb(255,255,0)">Yellow</theoplayer-radio-button>
+                    <theoplayer-radio-button value="rgb(0,255,255)">Cyan</theoplayer-radio-button>
+                </theoplayer-text-track-style-radio-group>
+            </theoplayer-menu>
+        </theoplayer-menu-group>
+
+        <theoplayer-error-display slot="error"></theoplayer-error-display>
+    </theoplayer-ui>
+    ```
+
+    [📜 View full source on GitHub](https://github.com/THEOplayer/web-ui/blob/main/docs/static/open-video-ui/v2/examples/web/text-tracks/demo.html)
+
+</details>
diff --git a/docs/examples/default-ui/_category_.json b/docs/examples/default-ui/_category_.json
@@ -0,0 +1,7 @@
+{
+  "label": "Default UI",
+  "position": 10,
+  "collapsible": true,
+  "collapsed": true,
+  "description": "Samples demonstrating how to modify the default styling of the player."
+}
diff --git a/docs/examples/ads.mdx → docs/examples/default-ui/ads.mdx b/docs/examples/ads.mdx → docs/examples/default-ui/ads.mdx
@@ -1,23 +1,22 @@
 ---
-sidebar_position: 11
+sidebar_position: 2
 sidebar_custom_props: { 'icon': '💰' }
+slug: /web/examples/ads
 ---
 
 # Advertisements
 
-The default UI has full support for advertisements.
-
-During playback, it shows yellow ad markers on the seek bar to indicate the times when the content will be interrupted by an ad.
-
-While playing an ad, the UI shows ad-specific controls such as a skip button and a countdown. These controls are also mobile-aware, for example a
-dedicated clickthrough button replaces the regular clickthrough behavior on desktop.
-
-import Example from '../components/Example';
+import Example from '../../components/Example';
 import useBaseUrl from '@docusaurus/useBaseUrl';
-import styles from './shared.module.css';
+import styles from '../shared.module.css';
 
 <Example className={styles.player} hideSource src={useBaseUrl('/open-video-ui/v2/examples/web/ads/demo.html')}></Example>
 
+The default UI has full support for advertisements.
+
+During playback, it shows yellow ad markers on the seek bar to indicate the times when the content will be interrupted by an ad. While playing an ad, the UI shows ad-specific controls such as a skip button and a countdown. These controls are also mobile-aware, for example a
+dedicated clickthrough button replaces the regular clickthrough behavior on desktop.
+
 <details>
     <summary>Code</summary>
     ```js showLineNumbers