# Activity Feed (/docs/blocks/activity-feed)

```tsx title="components/examples/activity-feed-demo.tsx"
"use client";

import { useState } from "react";

import { ActivityFeed } from "@/components/blocks/stream-manager/activity-feed";
import type { ActivityItem } from "@/components/blocks/stream-manager/activity-feed";
import { StatusDot } from "@/components/status-dot";
import { Badge } from "@/components/ui/badge";
import { Empty, EmptyDescription, EmptyHeader } from "@/components/ui/empty";
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs";

const ITEMS: ActivityItem[] = [
  {
    highlight: { phase: "live" },
    id: "a1",
    kind: "super-chat",
    line: "Sent a $20.00 Super Chat",
    message: "Bought my first capture card because of this channel!",
    messageId: "m-super",
    name: "Maya Chen",
    platform: "youtube",
    short: "Super Chat · $20.00",
    time: "now",
  },
  {
    id: "a2",
    kind: "subscription",
    line: "Resubscribed for 14 months at Tier 1",
    message: "Fourteen months of two-camera streams.",
    name: "nightowl_jonas",
    platform: "twitch",
    short: "Resub · 14 months",
    time: "1m",
  },
  {
    gift: true,
    id: "a3",
    kind: "subscription",
    line: "Gifted 5 Tier 1 subs to the community",
    name: "kai.streams",
    platform: "twitch",
    short: "Gifted 5 subs",
    time: "3m",
  },
  {
    id: "a4",
    kind: "raid",
    line: "Raided with 42 viewers",
    name: "pixelpilot",
    platform: "twitch",
    short: "Raid · 42 viewers",
    time: "6m",
  },
  {
    id: "a5",
    kind: "follow",
    line: "3 new followers on X",
    name: "3 new followers",
    platform: "x",
    short: "",
    time: "9m",
    unnamed: true,
  },
  {
    id: "a6",
    kind: "follow",
    line: "Subscribed to your channel",
    name: "Hana Ito",
    platform: "youtube",
    short: "New subscriber",
    time: "12m",
  },
];

const ActivityFeedDemo = () => {
  const [pane, setPane] = useState<string>("activity");
  const [autoShow, setAutoShow] = useState(true);
  return (
    <div className="rounded-panel bg-glass-content flex h-[30rem] w-full max-w-md flex-col overflow-hidden border">
      <div className="border-border flex items-center border-b px-2 py-1.5">
        <Tabs onValueChange={(value) => setPane(String(value))} value={pane}>
          <TabsList>
            <TabsTrigger value="activity">Activity</TabsTrigger>
            <TabsTrigger value="buddy">
              <StatusDot tone="good" />
              Orcle
              <Badge variant="outline">1</Badge>
            </TabsTrigger>
          </TabsList>
        </Tabs>
      </div>
      {pane === "activity" ? (
        <ActivityFeed
          autoShow={autoShow}
          items={ITEMS}
          onAutoShowChange={setAutoShow}
          onShowOnStream={() => null}
          onThank={() => null}
          platforms={["youtube", "twitch", "x"]}
        />
      ) : (
        <Empty className="min-h-0 flex-1">
          <EmptyHeader>
            <EmptyDescription>
              Buddy reads chat during a live stream: questions, flags and the
              room&apos;s mood.
            </EmptyDescription>
          </EmptyHeader>
        </Empty>
      )}
    </div>
  );
};

export default ActivityFeedDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/activity-feed
```

## Usage

```tsx
import { ActivityFeed } from "@/components/blocks/stream-manager/activity-feed";
import type { ActivityItem } from "@/components/blocks/stream-manager/activity-feed";
```

```tsx
const items: ActivityItem[] = [
  {
    id: "a1",
    kind: "subscription",
    platform: "twitch",
    name: "nightowl_jonas",
    short: "Resub · 14 months",
    line: "Resubscribed for 14 months at Tier 1",
    message: "Fourteen months of two-camera streams.",
    time: "1m",
  },
];

<ActivityFeed
  items={items}
  onShowOnStream={showOnStream}
  onThank={thankInChat}
  platforms={["youtube", "twitch", "x"]}
/>;
```

Activity is structured events, never chat text. Each event is plain data: who (`name`), the fact at a glance (`short`: "Resub · 14 months"), the sentence (`line`, on hover and for Copy), the viewer's own words, and the time as you show it ("now", "2m"). The pane derives each event's kind chip from its `kind`.

- **A row leads with who.** An event about one named viewer or channel shows their avatar, or their initials until it loads. Counts the platform never named (`unnamed`), announcements and destinations keep their glyph.
- **One tint per row,** like chat: a channel point reward paints `bg-reward/8`, a tip chat's paid fill without its ring, and a sub or membership the member plate. The row on stream wears the live plate instead.
- **The ⋯ menu** holds Show on stream (with a `messageId`), Thank in chat, Reconnect Twitch on an unnamed Twitch count, and Copy.

The pane's tabs, Activity beside Buddy, belong to the window: the [Stream Manager](/docs/blocks/stream-manager) puts them over the pane, as the demo does.

## Examples

### Empty, with what a platform can't share

Until something happens the pane says what will show, and `note` says what never can on these platforms: `activityCapabilityNote(platforms, options)` writes it. With `twitchNeeds.followNames` and `onReconnectTwitch`, Reconnect Twitch asks for the permission that names each follower.

```tsx title="components/examples/activity-feed-empty.tsx"
"use client";

import {
  ActivityFeed,
  activityCapabilityNote,
} from "@/components/blocks/stream-manager/activity-feed";
import type { ChatPlatform } from "@/components/blocks/stream-manager/chat-platform";

const PLATFORMS: ChatPlatform[] = ["youtube", "twitch", "x"];

const ActivityFeedEmpty = () => (
  <div className="rounded-panel bg-glass-content flex h-72 w-full max-w-md flex-col overflow-hidden border">
    <ActivityFeed
      note={activityCapabilityNote(PLATFORMS, { twitchNeedsFollowNames: true })}
      onReconnectTwitch={() => null}
      platforms={PLATFORMS}
      twitchNeeds={{ followNames: true }}
    />
  </div>
);

export default ActivityFeedEmpty;
```

## Responsive

Inside the Stream Manager the filter strip follows the window's width: from 640 px the platform and kind chips are inline, with each kind's count, and below it they fold into one Filters menu. On its own the chips always show.

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `divide-y` | Flush rows split by hairlines |
| `chrome-row-live` | The row on stream |
| `chrome-row-member`, `bg-warning/10`, `bg-reward/8` | A sub or membership, a tip, a reward |
| `hover:bg-accent` | Hover, over any tint |
| `group/activity`, `group/kebab-host` | The row the time and the ⋯ wait for |
| `data-kind`, `data-row-tint`, `data-highlight-phase` | On each row |
| `data-slot` | `activity-feed`, `activity-row`, `activity-avatar`, `activity-glyph`, `activity-line` |

## Accessibility

The pane is a region named "Activity", and its rows an ordered list. A row's sentence is what a screen reader hears when the short fact says less; on screen it's the fact's tooltip, never a native `title`. The kind chips are a group named "Filter activity", each explained on hover. Auto-show's switch is named by what it does.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `readonly ActivityItem[]` | `[]` | — |
| `platforms` | `readonly ChatPlatform[]` | — | The platforms on this stream: the platform chips. |
| `note` | `string \| null` | — | What Activity can't show here, under the empty line. |
| `timestamps` | `"always" \| "hover"` | `"always"` | hover: a row's time waits for the pointer, as while live. |
| `onShowOnStream` | `(item) => void` | — | Show on stream, for rows with a messageId. |
| `onThank` | `(item) => void` | — | Thank in chat. |
| `twitchNeeds` | `{ followNames?: boolean; bitsAndPoints?: boolean }` | — | The Twitch permissions still missing. |
| `onReconnectTwitch` | `() => void` | — | Reconnect Twitch, wherever it's asked. |
| `autoShow` | `boolean` | `false` | — |
| `onAutoShowChange` | `(on: boolean) => void` | — | Shows the Auto-show switch. |

### ActivityItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | — | — |
| `kind` | `"follow" \| "subscription" \| "membership" \| "cheer" \| "super-chat" \| "super-sticker" \| "power-up" \| "redemption" \| "raid" \| "watch-streak" \| "announcement" \| "destination-failed" \| "destination-recovered"` | — | — |
| `platform` | `ChatPlatform` | — | — |
| `name` | `string` | — | Who: the viewer, the raiding channel, the destination. |
| `short` | `string` | — | "Resub · 14 months". |
| `line` | `string` | — | The sentence, on hover and for Copy. |
| `message` | `string` | — | The viewer's own words. |
| `time` | `string` | — | "now", "2m", "1h". |
| `at` | `string` | — | ISO, for the time element. |
| `messageId` | `string` | — | The chat message Show on stream puts on stream. |
| `authorAvatarUrl` | `string` | — | — |
| `gift` | `boolean` | — | A gifted sub or membership: the gift glyph. |
| `unnamed` | `boolean` | — | A count the platform never named. |
| `highlight` | `ChatMessageHighlight` | — | Its place on stream. |

`ACTIVITY_FILTERS`, `activityFilterFor`, `filterActivity`, `activityFilterCounts`, `activityRowShowsPerson`, `activityRowTint` and `activityRowActions` are the rules the pane follows.

# Chat Composer (/docs/blocks/chat-composer)

```tsx title="components/examples/chat-composer-demo.tsx"
"use client";

import { useEffect, useState } from "react";

import { ChatComposer } from "@/components/blocks/stream-manager/chat-composer";
import type { ChatComposerCommand } from "@/components/blocks/stream-manager/chat-composer";
import type { ChatDestination } from "@/components/blocks/stream-manager/chat-platform";

const DESTINATIONS: ChatDestination[] = [
  {
    accountLabel: "Night Owl Studio",
    id: "yt",
    platform: "youtube",
    state: "connected",
    write: "ready",
  },
  {
    accountLabel: "nightowlstudio",
    id: "tw",
    platform: "twitch",
    state: "connected",
    write: "ready",
  },
  { id: "x", platform: "x", state: "connected", write: "read-only" },
];

const COMMANDS: ChatComposerCommand[] = [
  {
    argument: true,
    hint: " [title] · Save a timeline point",
    value: "/marker",
  },
  { hint: " · Save the last 30 seconds as a clip", value: "/clip" },
  { hint: " · Save the last minute as a clip", value: "/clip 60" },
  { hint: " · Command help", value: "/help" },
];

const SEND_TIME_MS = 900;

const ChatComposerDemo = () => {
  const [pending, setPending] = useState(false);
  const [notice, setNotice] = useState<string | null>(null);
  useEffect(() => {
    if (!pending) {
      return;
    }
    const timer = setTimeout(() => setPending(false), SEND_TIME_MS);
    return () => clearTimeout(timer);
  }, [pending]);
  return (
    <div className="rounded-panel bg-glass-content w-full max-w-2xl overflow-hidden border">
      <ChatComposer
        commands={COMMANDS}
        destinations={DESTINATIONS}
        notice={notice}
        onCommand={(command) =>
          setNotice(
            command.startsWith("/marker")
              ? `Marker saved at 30:44 · ${command.slice(8).trim() || "Untitled marker"}`
              : "Saving the last 30 seconds as a clip…"
          )
        }
        onSend={() => {
          setNotice(null);
          setPending(true);
        }}
        pending={pending}
        placeholder="Message, /marker [title] or /clip…"
      />
    </div>
  );
};

export default ChatComposerDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/chat-composer
```

## Usage

```tsx
import { ChatComposer } from "@/components/blocks/stream-manager/chat-composer";
import type { ChatDestination } from "@/components/blocks/stream-manager/chat-platform";
```

```tsx
const destinations: ChatDestination[] = [
  { id: "yt", platform: "youtube", state: "connected", write: "ready" },
  { id: "tw", platform: "twitch", state: "connected", write: "ready" },
  { id: "x", platform: "x", state: "connected", write: "read-only" },
];

<ChatComposer
  destinations={destinations}
  onSend={(text, { destinationIds }) => send(text, destinationIds)}
  pending={sending}
/>;
```

A message goes to every destination whose `write` is `ready`. With more than one, the "To:" picker lets the streamer narrow a send; `onSend` then gets the picked `destinationIds`, and without a pick it gets none. The draft must fit the strictest destination it reaches: 200 characters, 140 with X.

The line under the field speaks only for the exceptions: a destination the send skips ("X read-only"), a failed send's reason with Retry, and "Sending…" while a send is on its way. A finished send says nothing: the message shows up in chat.

## Examples

### Local commands

Pass `commands` and the field completes them after "/": ↑ and ↓ move, Tab or ↵ completes. A command runs through `onCommand` and never posts to chat; "//" sends one literal slash. `notice` is the composer's answer, read politely: "Marker saved at 30:44 · Untitled marker". The demo above wires Videorc's `/marker` and `/clip`.

### A failed send

`failures` names each destination a send didn't reach, with its reason; `onRetry` adds Retry. YouTube's chip names it in words: its mark may not shrink to a chip's 12 px.

```tsx title="components/examples/chat-composer-failure.tsx"
"use client";

import { useState } from "react";

import { ChatComposer } from "@/components/blocks/stream-manager/chat-composer";
import type { ChatSendFailure } from "@/components/blocks/stream-manager/chat-composer";
import type { ChatDestination } from "@/components/blocks/stream-manager/chat-platform";

const DESTINATIONS: ChatDestination[] = [
  { id: "yt", platform: "youtube", state: "connected", write: "ready" },
  { id: "tw", platform: "twitch", state: "connected", write: "ready" },
  { id: "x", platform: "x", state: "connected", write: "read-only" },
];

const FAILURES: ChatSendFailure[] = [
  {
    destinationId: "tw",
    platform: "twitch",
    reason: "Twitch rejected this message: slow mode is on.",
  },
];

const ChatComposerFailure = () => {
  const [failures, setFailures] = useState(FAILURES);
  return (
    <div className="rounded-panel bg-glass-content w-full max-w-2xl overflow-hidden border">
      <ChatComposer
        defaultValue="Thanks for the raid, everyone!"
        destinations={DESTINATIONS}
        failures={failures}
        onRetry={() => setFailures([])}
        onSend={() => setFailures([])}
      />
    </div>
  );
};

export default ChatComposerFailure;
```

### The window owns the draft

Pass `value` and `onValueChange` when something else fills the field, such as a row's ⋯ Reply that writes "@Maya Chen ", and `inputRef` for ⌘L to focus it.

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `border-t` `px-2 py-2` | The flush region under a hairline, never a card |
| `InputGroup` | The field, its picker, count, key and send |
| `text-label` | The count and the notes line |
| `Badge` `destructive` | A failed destination |
| `data-slot` | `chat-composer`, `chat-composer-count`, `chat-composer-status` |

## Keyboard

| Key                       | Action                               |
| ------------------------- | ------------------------------------ |
| <kbd>Enter</kbd>          | Sends, or runs a local command       |
| <kbd>↑</kbd> <kbd>↓</kbd> | Move through the command completions |
| <kbd>Tab</kbd>            | Completes the chosen command         |
| <kbd>Esc</kbd>            | Closes the completions               |

## Accessibility

The field is named "Message", or "Message or local command" with commands. The send button's name says where it sends: "Send message to all writable destinations", "Send message to Twitch", or why it can't. The picker is named "Send to: All". `notice` is a polite status, and an over-limit count carries the alert icon as well as its number.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `destinations` | `readonly ChatDestination[]` | — | — |
| `onSend` | `(text: string, options: { destinationIds?: string[] }) => void` | — | — |
| `commands` | `readonly ChatComposerCommand[]` | — | Local commands to complete after "/". |
| `onCommand` | `(text: string) => void` | — | Runs a local command. |
| `pending` | `boolean` | `false` | A send is on its way: Sending… |
| `failures` | `readonly ChatSendFailure[]` | `[]` | — |
| `onRetry` | `() => void` | — | Adds Retry under a failed send. |
| `notice` | `ReactNode` | — | The composer's own answer. |
| `value` | `string` | — | The draft, when the window owns it. |
| `defaultValue` | `string` | `""` | — |
| `onValueChange` | `(value: string) => void` | — | — |
| `placeholder` | `string` | `"Send a message…"` | — |
| `inputRef` | `RefObject<HTMLInputElement \| null>` | — | For ⌘L. |
| `platform` | `string` | — | darwin, win32, linux…: how ↵ is printed. |

### ChatComposerCommand

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | "/marker" |
| `hint` | `string` | — | " [title] · Save a timeline point" |
| `argument` | `boolean` | — | It takes an argument: completing it leaves a space. |

### ChatSendFailure

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `destinationId` | `string` | — | — |
| `platform` | `ChatPlatform` | — | — |
| `reason` | `string` | — | The destination's reason, in a sentence. |

`chatDestinationNotes(destinations, sendPlatforms)` and `chatDraftMaxChars(platforms)` are the rules the composer follows, for a status of your own.

# Chat Message (/docs/blocks/chat-message)

```tsx title="components/examples/chat-message-demo.tsx"
"use client";

import { useState } from "react";

import { ChatMessage } from "@/components/blocks/stream-manager/chat-message";
import type { ChatMessageData } from "@/components/blocks/stream-manager/chat-message";

// While live the rows keep their time out of sight until the pointer comes:
// these carry none at all, so the words have the room.
const MESSAGES: ChatMessageData[] = [
  {
    authorName: "Maya Chen",
    id: "m1",
    platform: "youtube",
    text: "Which microphone are you using on stream today?",
  },
  {
    authorName: "jonas",
    authorRoles: ["member"],
    id: "m2",
    platform: "twitch",
    text: "The new two-camera scene looks so clean.",
  },
  {
    authorName: "priya",
    id: "m3",
    platform: "x",
    text: "Watching from Lisbon. Audio is perfectly in sync!",
  },
];

const ChatMessageDemo = () => {
  const [onStream, setOnStream] = useState<string | null>("m3");
  return (
    <ol
      aria-label="Chat messages"
      className="flex w-full max-w-2xl flex-col gap-1"
    >
      {MESSAGES.map((message) => (
        <ChatMessage
          highlight={{ phase: message.id === onStream ? "live" : "idle" }}
          key={message.id}
          message={message}
          onHighlight={(target) =>
            setOnStream((current) => (current === target.id ? null : target.id))
          }
          onReply={() => null}
        />
      ))}
    </ol>
  );
};

export default ChatMessageDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/chat-message
```

## Usage

```tsx
import { ChatMessage } from "@/components/blocks/stream-manager/chat-message";
import type { ChatMessageData } from "@/components/blocks/stream-manager/chat-message";
```

```tsx
const message: ChatMessageData = {
  id: "m1",
  platform: "youtube",
  authorName: "Maya Chen",
  text: "Which microphone are you using on stream today?",
  time: "8:41 PM",
};

<ol aria-label="Chat messages">
  <ChatMessage
    highlight={{ phase: onStream === message.id ? "live" : "idle" }}
    message={message}
    onHighlight={toggleOnStream}
    onReply={replyTo}
  />
</ol>;
```

A message is plain data. `ChatMessage` renders one `<li>`, so put the rows in an `<ol>`. With `onHighlight` the row is one button: a click puts the message on stream, and a click on the row that's on stream takes it off. Without it the row is plain text, as in History.

Format `time` yourself, once, so the server and the browser agree: `formatChatTime(receivedAt)` gives Videorc's "8:42 PM".

## Examples

### Every state

The row on stream wears the live chrome plate. A member's row is the quieter plate with a member-hue edge, a paid message is the warning fill with a hairline ring, and Buddy's "Talking about this" is the flat accent. A row paints one of them at most, and the row on stream beats them all. Chips sit after the name: roles, first chat, `@you` for a mention, the amount, Buddy's mark, the stream state and the removal. A failed show and an unusual removal say why on the row's own line.

```tsx title="components/examples/chat-message-states.tsx"
"use client";

import { ChatMessage } from "@/components/blocks/stream-manager/chat-message";
import type { ChatMessageProps } from "@/components/blocks/stream-manager/chat-message";

type Row = Omit<ChatMessageProps, "onHighlight"> & { highlightable?: boolean };

const ROWS: Row[] = [
  {
    highlight: { phase: "live" },
    message: {
      authorName: "Priya Raman",
      id: "on-stream",
      platform: "x",
      text: "On stream: the chrome plate with its polished edge.",
      time: "8:40 PM",
    },
  },
  {
    highlight: { phase: "applying" },
    message: {
      authorName: "Leo Park",
      id: "applying",
      platform: "youtube",
      text: "Applying: the row waits while Studio puts it on stream.",
      time: "8:40 PM",
    },
  },
  {
    highlight: {
      phase: "failed",
      reason: "Studio didn't answer. Try again.",
    },
    message: {
      authorName: "Sam Okafor",
      id: "failed",
      platform: "twitch",
      text: "Failed: the reason is the row's own line.",
      time: "8:41 PM",
    },
  },
  {
    message: {
      authorName: "nightowl_jonas",
      authorRoles: ["member"],
      id: "member",
      platform: "twitch",
      text: "A member's message wears the quieter plate with a member-hue edge.",
      time: "8:41 PM",
    },
  },
  {
    message: {
      amountText: "$5.00",
      authorName: "Maya Chen",
      id: "paid",
      kind: "paid",
      platform: "youtube",
      text: "A Super Chat: the warning fill and its hairline ring.",
      time: "8:41 PM",
    },
  },
  {
    mentionNames: ["@nightowlstudio"],
    message: {
      authorName: "kai.streams",
      firstMessage: true,
      id: "mention",
      platform: "twitch",
      text: "@nightowlstudio first time here, is this the two-camera setup?",
      time: "8:42 PM",
    },
  },
  {
    message: {
      authorName: "Ana Silva",
      authorRoles: ["moderator"],
      id: "reply",
      platform: "youtube",
      reply: {
        authorName: "Maya Chen",
        text: "Which microphone are you using?",
      },
      text: "It's the Shure MV7, he said it last week.",
      time: "8:42 PM",
    },
  },
  {
    message: {
      authorName: "Leo Park",
      id: "spotlight",
      platform: "youtube",
      text: "Buddy heard you talking about this one.",
      time: "8:43 PM",
    },
    spotlight: true,
  },
  {
    message: {
      authorName: "Hana Ito",
      id: "suggested",
      platform: "x",
      text: "This stream got me to finally set up my own studio.",
      time: "8:43 PM",
    },
    suggested: true,
  },
  {
    flag: {
      action: "Remove?",
      detail: "Buddy flagged this as spam: a link repeated in chat.",
      label: "Spam",
      severity: "high",
    },
    message: {
      authorName: "promo_bot_77",
      id: "flagged",
      platform: "twitch",
      text: "free followers at a site you've never heard of",
      time: "8:43 PM",
    },
  },
  {
    message: {
      authorName: "promo_bot_12",
      id: "removing",
      platform: "twitch",
      text: "free followers, again",
      time: "8:44 PM",
    },
    removal: { kind: "removing" },
  },
  {
    highlightable: false,
    message: {
      authorName: "promo_bot_77",
      deleted: true,
      id: "removed",
      platform: "twitch",
      text: "free followers at a site you've never heard of",
      time: "8:44 PM",
    },
    removal: { detail: "Removed by you on Twitch.", kind: "removed" },
  },
  {
    highlightable: false,
    message: {
      authorName: "Twitch",
      id: "moderation",
      kind: "moderation",
      platform: "twitch",
      text: "promo_bot_77 was timed out for 10 minutes.",
      time: "8:44 PM",
    },
  },
];

const noop = () => null;

const ChatMessageStates = () => (
  <ol
    aria-label="Chat messages"
    className="flex w-full max-w-2xl flex-col gap-1"
  >
    {ROWS.map(({ highlightable = true, ...row }) => (
      <ChatMessage
        {...row}
        key={row.message.id}
        onHighlight={highlightable ? noop : undefined}
        onRemoveFromChat={row.flag ? noop : undefined}
        onReply={noop}
      />
    ))}
  </ol>
);

export default ChatMessageStates;
```

### Compact

`density="compact"` sets 12 px text and a 32 px avatar, for a narrow rail beside the Studio. The Stream Manager keeps the 15 px rows.

```tsx title="components/examples/chat-message-compact.tsx"
"use client";

import { ChatMessage } from "@/components/blocks/stream-manager/chat-message";
import type { ChatMessageData } from "@/components/blocks/stream-manager/chat-message";

const MESSAGES: ChatMessageData[] = [
  {
    authorName: "Maya Chen",
    id: "c1",
    platform: "youtube",
    text: "Which microphone are you using on stream today?",
    time: "8:41 PM",
  },
  {
    authorName: "nightowl_jonas",
    authorRoles: ["member"],
    id: "c2",
    platform: "twitch",
    text: "The new two-camera scene looks so clean.",
    time: "8:42 PM",
  },
  {
    authorName: "Priya Raman",
    id: "c3",
    platform: "x",
    text: "Watching from Lisbon.",
    time: "8:42 PM",
  },
];

const ChatMessageCompact = () => (
  <ol
    aria-label="Chat messages"
    className="flex w-full max-w-sm flex-col gap-1"
  >
    {MESSAGES.map((message) => (
      <ChatMessage density="compact" key={message.id} message={message} />
    ))}
  </ol>
);

export default ChatMessageCompact;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `chrome-row-live` | The row on stream (`CHROME_ROW_CLASS.live`) |
| `chrome-row-member` | A member's row (`CHROME_ROW_CLASS.member`) |
| `bg-warning/10 ring-warning/30` | A paid message |
| `bg-accent` | The message the streamer is talking about |
| `Badge` `chrome`, `destructive`, `warning`, `plate` | On stream, Failed, the amount, Member |
| `group/chat-message`, `group/kebab-host` | The row the time and the ⋯ wait for |
| `data-highlight-phase` | `idle`, `applying`, `live` or `failed` |
| `data-row-tint` | `paid`, `spotlight` or `member` |
| `data-mention`, `data-member` | Set on a mention and on a member's row |
| `data-slot` | `chat-message`, `chat-message-author`, `chat-message-text`, `chat-message-reply`, `chat-message-problem`, `chat-message-outcome` |

## Keyboard

| Key | Action |
| --- | --- |
| <kbd>Enter</kbd> <kbd>Space</kbd> | Puts the message on stream, or takes it off |
| <kbd>Tab</kbd> | Moves to the row's ⋯ menu |

## Accessibility

A highlightable row is one button named by what it says: author, platform and words ("Maya Chen on YouTube: Which microphone…"). `aria-pressed` says it's on stream and the description says what a click does, then any outcome the row shows. A drag that selects words in the row copies them and never puts the message on stream. The time and the ⋯ wait for the pointer while live (`timestamps="hover"`) and appear with keyboard focus. Every chip that stands for more says it in a tooltip, never a native `title`.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `message` | `ChatMessageData` | — | — |
| `density` | `"comfortable" \| "compact"` | `"comfortable"` | 15 px rows with a 40 px avatar, or 12 px with 32 px. |
| `timestamps` | `"always" \| "hover"` | `"always"` | hover: the time waits for the pointer, as while live. |
| `highlight` | `ChatMessageHighlight` | `{ phase: "idle" }` | — |
| `removal` | `ChatMessageRemoval \| null` | — | — |
| `flag` | `ChatMessageFlag` | — | What Buddy flagged on it. |
| `suggested` | `boolean` | `false` | Buddy suggests showing it. Shown only on an idle, highlightable row. |
| `spotlight` | `boolean` | `false` | The streamer is talking about it: Talking about this. |
| `mentionNames` | `readonly string[]` | `[]` | The streamer's own accounts: a message naming one shows @you. |
| `onHighlight` | `(message) => void` | — | Makes the row a button that puts the message on stream or takes it off. |
| `onReply` | `(message) => void` | — | Adds Reply to the ⋯ menu. |
| `onCopy` | `(message) => void` | — | Copy's action. Copies "Author: text" to the clipboard when absent. |
| `onRemoveFromChat` | `(message) => void` | — | Adds Remove from chat, destructive and last. |
| `removeFromChatReason` | `string \| null` | — | Keeps Remove from chat, disabled, with this reason on hover. |
| `tabIndex` | `number` | `0` | -1 on every row but the active one in a roving-focus list. |
| `ref` | `Ref<HTMLLIElement>` | — | For a virtualized list to measure it. |
| `style` | `CSSProperties` | — | For a virtualized list to place it. |

### ChatMessageData

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | — | — |
| `platform` | `ChatPlatform` | — | Where it came from. |
| `authorName` | `string` | — | — |
| `authorAvatarUrl` | `string` | — | Initials show until it loads, and without one. |
| `authorRoles` | `("owner" \| "moderator" \| "vip" \| "member")[]` | — | Host, Mod, VIP and Member chips. A member's row wears the member plate. |
| `text` | `string` | — | — |
| `kind` | `"message" \| "paid" \| "membership" \| "system" \| "moderation"` | `"message"` | System and moderation lines are italic and never go on stream. |
| `amountText` | `string` | — | A paid message's amount: "$5.00". |
| `firstMessage` | `boolean` | — | First chat. |
| `reply` | `{ authorName: string; text: string }` | — | The message it answers, above its own words. |
| `deleted` | `boolean` | — | Struck through, never on stream. |
| `time` | `string` | — | The time as shown: "8:42 PM". |
| `receivedAt` | `string` | — | ISO, for the time element. |

### ChatMessageHighlight

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `phase` | `"idle" \| "applying" \| "live" \| "failed"` | — | — |
| `reason` | `string` | — | Why a show failed, on the row's own line. |
| `commandError` | `string` | — | A failed action on a message already on stream. |

### ChatMessageRemoval

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` | `"removing" \| "removed" \| "hidden" \| "failed" \| "unknown"` | — | Removing…, Removed, Hidden in Videorc, Not removed, Unconfirmed. |
| `detail` | `string \| null` | — | The outcome: on hover for a plain removal, the row's own line otherwise. |

### ChatMessageFlag

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | — | The chip: "Spam". |
| `detail` | `string` | — | Why Buddy flagged it, on hover. |
| `severity` | `"high" \| "low"` | — | high tints the chip. |
| `action` | `string` | — | A suggestion after the chip: "Remove?". |

### Helpers

`HighlightStatus` and `RemovalStatus` are the row's two status chips, for rows of your own that share the slot (the [Activity Feed](/docs/blocks/activity-feed) does). `chatMessageMenu(message, options)` builds the ⋯ items; `chatMessageMentions(message, names)`, `chatMessageCanHighlight(message)`, `chatMessageInitials(name)` and `formatChatTime(iso)` are the rules the row follows.

# Chat Platform (/docs/blocks/chat-platform)

```tsx title="components/examples/chat-platform-demo.tsx"
"use client";

import {
  CHAT_PLATFORM_LABELS,
  ChatPlatformIcon,
} from "@/components/blocks/stream-manager/chat-platform";
import type { ChatPlatform } from "@/components/blocks/stream-manager/chat-platform";

const PLATFORMS: ChatPlatform[] = [
  "youtube",
  "twitch",
  "x",
  "tiktok",
  "instagram",
  "facebook",
  "custom",
];

const ChatPlatformDemo = () => (
  <ul className="flex flex-wrap items-center gap-x-5 gap-y-3">
    {PLATFORMS.map((platform) => (
      <li className="flex items-center gap-2 text-sm" key={platform}>
        <ChatPlatformIcon decorative platform={platform} />
        {CHAT_PLATFORM_LABELS[platform]}
      </li>
    ))}
  </ul>
);

export default ChatPlatformDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/chat-platform
```

## Usage

```tsx
import {
  CHAT_PLATFORM_LABELS,
  ChatPlatformIcon,
  chatStateLabel,
} from "@/components/blocks/stream-manager/chat-platform";
```

```tsx
<ChatPlatformIcon platform="twitch" />
```

Every Stream Manager part names a platform through it: a message's mark, the filter chips, the stats' hover cards and the status bar's chat states. Pass `decorative` when the words beside the mark already name the platform.

## Examples

### Chat states

`chatStateLabel(destination)` turns a destination's connection into Videorc's chat vocabulary: "Connected", "Read-only", "Reconnect to send", "Reconnecting…". It never says "receive-only", and never shows a raw value.

```tsx title="components/examples/chat-platform-states.tsx"
"use client";

import {
  CHAT_PLATFORM_LABELS,
  ChatPlatformIcon,
  chatStateLabel,
} from "@/components/blocks/stream-manager/chat-platform";
import type { ChatDestination } from "@/components/blocks/stream-manager/chat-platform";

const DESTINATIONS: ChatDestination[] = [
  { id: "yt", platform: "youtube", state: "connected", write: "ready" },
  {
    id: "tw",
    platform: "twitch",
    state: "connected",
    write: "missing-scope",
  },
  { id: "x", platform: "x", state: "connected", write: "read-only" },
  { id: "tt", platform: "tiktok", state: "reconnecting" },
];

const ChatPlatformStates = () => (
  <ul className="flex w-full max-w-xs flex-col gap-2 text-sm">
    {DESTINATIONS.map((destination) => (
      <li className="flex items-center gap-2" key={destination.id}>
        <ChatPlatformIcon decorative platform={destination.platform} />
        <span className="flex-1">
          {CHAT_PLATFORM_LABELS[destination.platform]}
        </span>
        <span className="text-muted-foreground">
          {chatStateLabel(destination)}
        </span>
      </li>
    ))}
  </ul>
);

export default ChatPlatformStates;
```

## The marks

Platform marks are the one place saturated colour is allowed in the chrome. Each mark is 20 px wherever it appears: YouTube's icon may not go below 20 px, so the others match it, and YouTube keeps clear space after it. A surface with no room for 20 px, such as a [Badge](/docs/components/badge), leaves the mark out and keeps the platform's name. The glyphs come from [Icons](/docs/concepts/icons) (`YoutubeIcon`, `TwitchIcon`, `XPlatformIcon`…), so swapping one there swaps it here.

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `text-platform-youtube`, `text-platform-twitch-ink`, `text-platform-facebook`, `text-platform-instagram` | The brand tints |
| `text-foreground` | X and TikTok: black or white by theme |
| `size-5` | The 20 px mark |
| `data-platform` | The platform the mark stands for |
| `data-slot="chat-platform-icon"` | The mark |

## Accessibility

A mark is an image named by its platform. With `decorative` it's hidden from assistive tech, so the platform is named once.

## API reference

### ChatPlatformIcon

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `platform` | `"youtube" \| "twitch" \| "x" \| "facebook" \| "tiktok" \| "instagram" \| "custom"` | — | — |
| `decorative` | `boolean` | `false` | Hidden from assistive tech, for a mark beside its platform's name. |
| `className` | `string` | — | Spacing; the size stays 20 px. |

### ChatDestination

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | — | — |
| `platform` | `ChatPlatform` | — | — |
| `state` | `"connected" \| "connecting" \| "reconnecting" \| "waiting" \| "paused" \| "failed" \| "ended" \| "off" \| "unavailable"` | — | The chat connection. |
| `write` | `"ready" \| "read-only" \| "missing-scope" \| "failed"` | `"read-only"` | Whether Videorc can send to it. |
| `accountLabel` | `string` | — | The account chat is read as. |
| `message` | `string` | — | The destination's own words when chat is stuck. |

`CHAT_PLATFORM_LABELS` maps each platform to its one name ("X", never "X / Twitter"; "Custom RTMP", never "Custom").

# Chat Toolbar (/docs/blocks/chat-toolbar)

```tsx title="components/examples/chat-toolbar-demo.tsx"
"use client";

import { useState } from "react";

import { ChatMessage } from "@/components/blocks/stream-manager/chat-message";
import type { ChatMessageData } from "@/components/blocks/stream-manager/chat-message";
import {
  ChatToolbar,
  DEFAULT_CHAT_FILTER,
  filterChatMessages,
} from "@/components/blocks/stream-manager/chat-toolbar";
import type { ChatFilter } from "@/components/blocks/stream-manager/chat-toolbar";

const MESSAGES: ChatMessageData[] = [
  {
    authorName: "Maya Chen",
    id: "t1",
    platform: "youtube",
    text: "Which microphone are you using on stream today?",
    time: "8:41 PM",
  },
  {
    authorName: "nightowl_jonas",
    authorRoles: ["member"],
    id: "t2",
    platform: "twitch",
    text: "@nightowlstudio the new two-camera scene looks so clean.",
    time: "8:42 PM",
  },
  {
    authorName: "Priya Raman",
    id: "t3",
    platform: "x",
    text: "Watching from Lisbon. Audio is perfectly in sync!",
    time: "8:42 PM",
  },
];

/** Buddy's open question is about Maya's message. */
const QUESTION_IDS = new Set(["t1"]);
const MENTION_NAMES = ["@nightowlstudio"];

const ChatToolbarDemo = () => {
  const [filter, setFilter] = useState<ChatFilter>(DEFAULT_CHAT_FILTER);
  const shown = filterChatMessages(MESSAGES, filter, {
    mentionNames: MENTION_NAMES,
    questionIds: QUESTION_IDS,
  });
  return (
    <div className="rounded-panel bg-glass-content flex w-full max-w-2xl flex-col overflow-hidden border">
      <ChatToolbar
        filter={filter}
        onFilterChange={setFilter}
        platforms={["youtube", "twitch", "x"]}
        questions
      />
      <ol
        aria-label="Chat messages"
        className="flex h-56 flex-col gap-1 px-2 py-1"
      >
        {shown.map((message) => (
          <ChatMessage
            key={message.id}
            mentionNames={MENTION_NAMES}
            message={message}
          />
        ))}
        {shown.length === 0 ? (
          <li className="text-muted-foreground m-auto text-sm">
            No messages match these filters.
          </li>
        ) : null}
      </ol>
    </div>
  );
};

export default ChatToolbarDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/chat-toolbar
```

## Usage

```tsx
import {
  ChatToolbar,
  DEFAULT_CHAT_FILTER,
  filterChatMessages,
} from "@/components/blocks/stream-manager/chat-toolbar";
import type { ChatFilter } from "@/components/blocks/stream-manager/chat-toolbar";
```

```tsx
const [filter, setFilter] = useState<ChatFilter>(DEFAULT_CHAT_FILTER);
const shown = filterChatMessages(messages, filter, {
  mentionNames: ["@nightowlstudio"],
  questionIds,
});

<ChatToolbar
  filter={filter}
  onFilterChange={setFilter}
  platforms={["youtube", "twitch", "x"]}
  questions={questionIds.size > 0}
/>;
```

The filter is plain data you own:

```ts
interface ChatFilter {
  platform: ChatPlatform | "all";
  questions: boolean;
  mentions: boolean;
  search: string;
}
```

`filterChatMessages(messages, filter, { questionIds, mentionNames })` applies it: one platform, the messages behind Buddy's open questions, the ones that mention your accounts, and a search through words and names. `chatFilterActive(filter)` says whether anything narrows chat, for an empty state that reads "No messages match these filters."

The Questions chip shows while Buddy has open questions (`questions`), and stays while it's on. The search field takes ⌘F's focus through `searchRef`; Esc clears it.

## Responsive

Inside the [Stream Manager](/docs/blocks/stream-manager), the strip follows the window's own width: from 640 px the filters are inline chips, and below it they fold into one Filters menu with a count of what's on. On its own, outside the Stream Manager's container, the chips always show.

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `border-b` `px-2 py-1.5` | The strip, flush under a hairline |
| `ToggleGroup` | The filter chips; an active one is the chrome plate |
| `@max-[639px]/stream-manager:` | Where the chips fold into the Filters menu |
| `data-slot` | `chat-toolbar`, `chat-search` |

## Keyboard

| Key                       | Action                                           |
| ------------------------- | ------------------------------------------------ |
| <kbd>⌘</kbd> <kbd>F</kbd> | Searches chat, when the window wires `searchRef` |
| <kbd>Esc</kbd>            | In the search field, clears it and leaves        |

## Accessibility

The platform chips are a group named "Show chat from", and Questions and Mentions a group named "Chat filters", each explained on hover. The search field is named "Search chat". Below 640 px the Filters button is named "Chat filters" and its menu holds the same choices as radio and checkbox items.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `platforms` | `readonly ChatPlatform[]` | — | The platforms chat comes from: a chip each, from two up. |
| `filter` | `ChatFilter` | — | — |
| `onFilterChange` | `(filter: ChatFilter) => void` | — | — |
| `questions` | `boolean` | `false` | Buddy has open questions: the Questions chip shows. |
| `searchRef` | `Ref<HTMLInputElement>` | — | The search field, for ⌘F. |
| `platform` | `string` | — | darwin, win32, linux…: how ⌘F is printed. |

# Blocks (/docs/blocks)

Blocks are whole pieces of Videorc's screens, composed from the [components](/docs/components) and [primitives](/docs/primitives) the way Videorc composes them. They're presentational: plain data and callbacks go in, and nothing reaches for Electron, IPC or `window.videorc`. Your app owns the state and the side effects.

## Stream Manager

Videorc's live dashboard window: the stats bar, chat beside Activity and Buddy, and the status bar. [Stream Manager](/docs/blocks/stream-manager) is the whole window; each part installs on its own too.

- [Chat Message](/docs/blocks/chat-message): one message, the big-text row.
- [Chat Toolbar](/docs/blocks/chat-toolbar): platform chips, Questions, Mentions and search.
- [Chat Composer](/docs/blocks/chat-composer): the "To:" picker, the message field and send.
- [Stream Stats Bar](/docs/blocks/stream-stats-bar): the ON AIR clock, viewers, followers and the rest.
- [Activity Feed](/docs/blocks/activity-feed): follows, subs, gifts, tips and raids.
- [Stream Manager Status Bar](/docs/blocks/stream-manager-status-bar): each platform's chat state and the window's actions.
- [Platform Filter](/docs/blocks/platform-filter) and [Chat Platform](/docs/blocks/chat-platform): the pieces the parts share.

Every block sizes itself to its container, never the viewport, so it works in a window, a split pane or a docs preview alike.

# Platform Filter (/docs/blocks/platform-filter)

```tsx title="components/examples/platform-filter-demo.tsx"
"use client";

import { useState } from "react";

import { CHAT_PLATFORM_LABELS } from "@/components/blocks/stream-manager/chat-platform";
import { PlatformFilter } from "@/components/blocks/stream-manager/platform-filter";
import type { PlatformFilterValue } from "@/components/blocks/stream-manager/platform-filter";

const PlatformFilterDemo = () => {
  const [platform, setPlatform] = useState<PlatformFilterValue>("all");
  return (
    <div className="flex flex-col items-center gap-3">
      <PlatformFilter
        label="Show chat from"
        onValueChange={setPlatform}
        platforms={["youtube", "twitch", "x"]}
        value={platform}
      />
      <p aria-live="polite" className="text-meta text-muted-foreground">
        {platform === "all"
          ? "Chat from every platform."
          : `Only ${CHAT_PLATFORM_LABELS[platform]} chat.`}
      </p>
    </div>
  );
};

export default PlatformFilterDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/platform-filter
```

## Usage

```tsx
import {
  PlatformFilter,
  PlatformFilterMenuItems,
} from "@/components/blocks/stream-manager/platform-filter";
```

```tsx
<PlatformFilter
  label="Show chat from"
  onValueChange={setPlatform}
  platforms={["youtube", "twitch", "x"]}
  value={platform}
/>
```

Chat and Activity share it, so a platform filters the same way in both. A chip clicked again turns back to All. With one platform it renders nothing: there's nothing to filter by.

Below 640 px of Stream Manager the chips move into the pane's Filters menu: put `PlatformFilterMenuItems` inside a [Dropdown Menu](/docs/components/dropdown-menu), with the same props. [Chat Toolbar](/docs/blocks/chat-toolbar) does both.

## Theming

| Token or attribute | Meaning                                       |
| ------------------ | --------------------------------------------- |
| `ToggleGroup`      | The chips; the chosen one is the chrome plate |
| `ChatPlatformIcon` | Each platform's 20 px mark                    |

## Accessibility

The group is named by `label` ("Show chat from"). Each icon chip is named by its platform and says "Only YouTube" on hover. In the menu, the choice is a radio group under the same label, with "Every platform" first.

## API reference

### PlatformFilter

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `platforms` | `readonly ChatPlatform[]` | — | A chip each, in this order. Fewer than two renders nothing. |
| `value` | `ChatPlatform \| "all"` | — | — |
| `onValueChange` | `(value: ChatPlatform \| "all") => void` | — | — |
| `label` | `string` | — | The group's name: "Show chat from", "Show activity from". |

### PlatformFilterMenuItems

The same props, as a labelled radio group for a Filters menu.

# Stream Manager Status Bar (/docs/blocks/stream-manager-status-bar)

```tsx title="components/examples/stream-manager-status-bar-demo.tsx"
"use client";

import { useState } from "react";

import type { ChatDestination } from "@/components/blocks/stream-manager/chat-platform";
import { StreamManagerStatusBar } from "@/components/blocks/stream-manager/stream-manager-status-bar";
import type { HighlightPosition } from "@/components/blocks/stream-manager/stream-manager-status-bar";

const DESTINATIONS: ChatDestination[] = [
  {
    accountLabel: "Night Owl Studio",
    id: "yt",
    platform: "youtube",
    state: "connected",
    write: "ready",
  },
  {
    accountLabel: "nightowlstudio",
    id: "tw",
    platform: "twitch",
    state: "connected",
    write: "ready",
  },
  {
    accountLabel: "@nightowlstudio",
    id: "x",
    platform: "x",
    state: "connected",
    write: "read-only",
  },
];

const StreamManagerStatusBarDemo = () => {
  const [pinned, setPinned] = useState(true);
  const [position, setPosition] = useState<HighlightPosition>("bottom-left");
  const [screenHidden, setScreenHidden] = useState(false);
  const [said, setSaid] = useState("Every control says what it does on hover.");
  return (
    // The Stream Manager's container: the bar folds by its width.
    <div className="rounded-panel bg-glass-content @container/stream-manager flex h-44 w-full flex-col overflow-hidden border">
      <p
        aria-live="polite"
        className="text-meta text-muted-foreground flex flex-1 items-center justify-center px-4 text-center"
      >
        {said}
      </p>
      <StreamManagerStatusBar
        destinationNotes={{
          x: ["X live chat reads only on this stream."],
        }}
        destinations={DESTINATIONS}
        highlightPosition={position}
        onClear={() => setSaid("Chat and Activity were cleared.")}
        onFocusBuddy={() => setSaid("Buddy's pane comes forward.")}
        onHighlightPositionChange={setPosition}
        onMarkClip={(seconds) =>
          setSaid(
            seconds === 30
              ? "Saving the last 30 seconds as a clip…"
              : "Saving the last minute as a clip…"
          )
        }
        onOpenPreview={() => setSaid("The Preview window opens.")}
        onPinnedChange={setPinned}
        onScreenPrivacy={(hidden) => {
          setScreenHidden(hidden);
          setSaid(
            hidden
              ? "Your screen is hidden from viewers."
              : "Your screen shows again."
          );
        }}
        onSearchChat={() => setSaid("Chat's search takes the focus.")}
        onWriteInChat={() => setSaid("The composer takes the focus.")}
        pinned={pinned}
        screenHidden={screenHidden}
      />
    </div>
  );
};

export default StreamManagerStatusBarDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/stream-manager-status-bar
```

## Usage

```tsx
import { StreamManagerStatusBar } from "@/components/blocks/stream-manager/stream-manager-status-bar";
```

```tsx
<StreamManagerStatusBar
  destinations={destinations}
  onClear={clearView}
  onMarkClip={(seconds) => saveClip(seconds)}
  onOpenPreview={openPreview}
  onPinnedChange={setPinned}
  onSearchChat={focusSearch}
  onWriteInChat={focusComposer}
  pinned={pinned}
/>
```

The left side is chat, per destination: its 20 px mark and a status dot. Quiet when fine: a platform that reads and sends says nothing more, and a word appears only when something needs the streamer ("X read-only", "Twitch reconnect to send"), or the destination's own words when chat is stuck. The details open on hover and on focus: what chat can do there, the account it reads as, and any `destinationNotes`.

The right side is the window's controls, each one there only when you pass its callback, and every one labelled:

- the window's keys as clickable hints: ⌘F Search, ⌘L Write and ⌘J Buddy;
- Hide screen, Keep on top ([Pin Window Button](/docs/primitives/pin-window-button)) and Highlight position (a menu);
- Clip 30 s and 1 min, with the clip icon and words: mid-stream there's no time to hover;
- Banners (a menu of checks), Clear (it asks first, because it can't be undone) and Open Preview.

## Examples

### Narrow

Below 800 px of Stream Manager the hints keep their keys and the words go to screen readers. Below 640 px every control folds into one ⋯ menu, "More Stream Manager actions", with the stats bar's show, hide and reset choices; a dot that isn't green keeps its word beside it.

```tsx title="components/examples/stream-manager-status-bar-narrow.tsx"
"use client";

import { useState } from "react";

import type { ChatDestination } from "@/components/blocks/stream-manager/chat-platform";
import { StreamManagerStatusBar } from "@/components/blocks/stream-manager/stream-manager-status-bar";
import { DEFAULT_STATS_LAYOUT } from "@/components/blocks/stream-manager/stream-stats-bar";
import type { StatsLayout } from "@/components/blocks/stream-manager/stream-stats-bar";

const DESTINATIONS: ChatDestination[] = [
  { id: "yt", platform: "youtube", state: "connected", write: "ready" },
  {
    id: "tw",
    message: "Twitch chat is reconnecting. Messages wait until it's back.",
    platform: "twitch",
    state: "reconnecting",
    write: "ready",
  },
  { id: "x", platform: "x", state: "connected", write: "read-only" },
];

const StreamManagerStatusBarNarrow = () => {
  const [pinned, setPinned] = useState(false);
  const [layout, setLayout] = useState<StatsLayout>(DEFAULT_STATS_LAYOUT);
  return (
    <div className="rounded-panel bg-glass-content @container/stream-manager flex h-32 w-full max-w-sm flex-col justify-end overflow-hidden border">
      <StreamManagerStatusBar
        destinations={DESTINATIONS}
        onClear={() => null}
        onMarkClip={() => null}
        onOpenPreview={() => null}
        onPinnedChange={setPinned}
        onSearchChat={() => null}
        onStatsLayoutChange={setLayout}
        onWriteInChat={() => null}
        pinned={pinned}
        statsLayout={layout}
      />
    </div>
  );
};

export default StreamManagerStatusBarNarrow;
```

## Responsive

The bar folds by the width of the `@container/stream-manager` around it, never the viewport: from 1,040 px Hide screen shows its word, from 800 px the hints show theirs, and below 640 px the ⋯ menu takes over. The examples wrap it in that container; the [Stream Manager](/docs/blocks/stream-manager) is one. On its own, outside the container, every control shows.

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `h-8` | 32 px, not the shared 26: the 20 px marks need room |
| `StatusDot` | Each destination's tone: good, warn, error |
| `StatusBarHint`, `StatusBarAction` | The hints and the labelled actions |
| `@max-[639px]/stream-manager:` | Where the controls fold into the ⋯ menu |
| `data-slot` | `chat-states`, `chat-state`, `stream-manager-controls`, `stream-manager-actions` |

## Keyboard

| Key | Action |
| --- | --- |
| <kbd>Tab</kbd> | Moves through the chat states (each opens its details on focus) and the controls |
| <kbd>Enter</kbd> <kbd>Space</kbd> | Runs a control, or opens its menu |

The hints print the window's keys; the [Stream Manager](/docs/blocks/stream-manager) answers them.

## Accessibility

Each chat state is a button named by its first line ("X chat: read-only"). Every action has a name and a tooltip, never a native `title`; an icon alone is named by its tooltip. Hide screen says why when it can't run, through [Disabled Reason](/docs/components/disabled-reason). Clear asks in a [Confirm Dialog](/docs/primitives/confirm-dialog) first.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `destinations` | `readonly ChatDestination[]` | — | — |
| `destinationNotes` | `Partial<Record<ChatPlatform, readonly string[]>>` | — | More lines for a platform's hover card. |
| `onSearchChat` | `() => void` | — | ⌘F Search. |
| `onWriteInChat` | `() => void` | — | ⌘L Write. |
| `onFocusBuddy` | `() => void` | — | ⌘J Buddy. |
| `pinned` | `boolean` | `false` | — |
| `onPinnedChange` | `(pinned: boolean) => void` | — | Keep on top. |
| `highlightPosition` | `"top-left" \| "top-right" \| "bottom-left" \| "bottom-right"` | — | — |
| `onHighlightPositionChange` | `(position) => void` | — | — |
| `onMarkClip` | `(seconds: 30 \| 60) => void` | — | The two Clip buttons. |
| `screenHidden` | `boolean` | `false` | — |
| `onScreenPrivacy` | `(hidden: boolean) => void` | — | Hide screen, or Show screen. |
| `screenHideDisabledReason` | `string \| null` | — | Why a hide can't run now. Showing again always runs. |
| `banners` | `readonly { id: string; name: string; shown: boolean }[] \| null` | — | null until the list loads. |
| `onBanner` | `(action: BannerAction) => void` | — | — |
| `onClear` | `() => void` | — | Clear view, after it asks. |
| `onOpenPreview` | `() => void` | — | — |
| `statsLayout` | `StatsLayout` | — | For the ⋯ menu's Show or hide stats. |
| `onStatsLayoutChange` | `(layout: StatsLayout) => void` | — | — |
| `platform` | `string` | — | darwin, win32, linux…: how the keys are printed. |

# Stream Manager (/docs/blocks/stream-manager)

```tsx title="components/examples/stream-manager-demo.tsx"
"use client";

import { useEffect, useState } from "react";

import type { ActivityItem } from "@/components/blocks/stream-manager/activity-feed";
import type { ChatComposerCommand } from "@/components/blocks/stream-manager/chat-composer";
import type { ChatMessageData } from "@/components/blocks/stream-manager/chat-message";
import type { ChatDestination } from "@/components/blocks/stream-manager/chat-platform";
import { StreamManager } from "@/components/blocks/stream-manager/stream-manager";
import type { StreamHighlight } from "@/components/blocks/stream-manager/stream-manager";
import type { HighlightPosition } from "@/components/blocks/stream-manager/stream-manager-status-bar";
import { DEFAULT_STATS_LAYOUT } from "@/components/blocks/stream-manager/stream-stats-bar";
import type {
  StatItem,
  StatsLayout,
} from "@/components/blocks/stream-manager/stream-stats-bar";
import { SparkleIcon } from "@/components/icons";
import { StatusDot } from "@/components/status-dot";
import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert";
import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";

const STARTED_SECONDS = 30 * 60 + 44;
const SECONDS_PER_MINUTE = 60;
const TICK_MS = 1000;
const ARRIVAL_MS = 6000;
const APPLY_MS = 500;
const SEND_MS = 700;
const MOST_MESSAGES = 40;

const clock = (seconds: number): string =>
  `${Math.floor(seconds / SECONDS_PER_MINUTE)}:${String(seconds % SECONDS_PER_MINUTE).padStart(2, "0")}`;

const statItems = (seconds: number, chatPace: number): StatItem[] => [
  {
    badge: "live",
    description: `On air for ${clock(seconds)}`,
    details: [{ label: "Started", value: "8:12 PM" }],
    id: "session",
    label: "Session",
    tone: "neutral",
    value: clock(seconds),
  },
  {
    description: "1.2k viewers, peak 1.4k",
    details: [
      { label: "YouTube", platform: "youtube", value: "812" },
      { label: "Twitch", platform: "twitch", value: "356" },
      { label: "X", platform: "x", value: "64" },
      { label: "Peak", value: "1.4k" },
    ],
    id: "viewers",
    label: "Viewers",
    spark: [880, 940, 1010, 990, 1080, 1150, 1120, 1232],
    tone: "neutral",
    value: "1.2k",
  },
  {
    delta: "+12",
    description: "61,942 followers, +12 this stream",
    details: [
      {
        label: "YouTube subscribers",
        note: "+9 this stream",
        platform: "youtube",
        value: "48,310",
      },
      {
        label: "Twitch followers",
        note: "+3 this stream",
        platform: "twitch",
        value: "13,632",
      },
    ],
    id: "followers",
    label: "Followers",
    tone: "neutral",
    unit: "followers",
    value: "61,942",
  },
  {
    description: "8 new supporters this stream",
    details: [{ label: "New this stream", value: "8" }],
    id: "supporters",
    label: "Supporters this stream",
    tone: "neutral",
    unit: "supporters",
    value: "8",
  },
  {
    description: "Tips this stream: $20, 300 bits",
    details: [
      { label: "Super Chats (USD)", value: "$20" },
      { label: "Bits", value: "300" },
    ],
    id: "tips",
    label: "Tips this stream",
    tone: "neutral",
    value: "$20 · 300 bits",
  },
  {
    description: `${chatPace} messages a minute`,
    details: [
      { label: "Messages in the last minute", value: String(chatPace) },
    ],
    id: "chat",
    label: "Chat",
    tone: "neutral",
    unit: "msg/min",
    value: String(chatPace),
  },
];

const DESTINATIONS: ChatDestination[] = [
  {
    accountLabel: "Night Owl Studio",
    id: "yt",
    platform: "youtube",
    state: "connected",
    write: "ready",
  },
  {
    accountLabel: "nightowlstudio",
    id: "tw",
    platform: "twitch",
    state: "connected",
    write: "ready",
  },
  {
    accountLabel: "@nightowlstudio",
    id: "x",
    platform: "x",
    state: "connected",
    write: "read-only",
  },
];

const MESSAGES: ChatMessageData[] = [
  {
    authorName: "Maya Chen",
    id: "m1",
    platform: "youtube",
    text: "Which microphone are you using on stream today?",
    time: "8:39 PM",
  },
  {
    authorName: "nightowl_jonas",
    authorRoles: ["member"],
    id: "m2",
    platform: "twitch",
    text: "The new two-camera scene looks so clean.",
    time: "8:40 PM",
  },
  {
    authorName: "Priya Raman",
    id: "m3",
    platform: "x",
    text: "Watching from Lisbon. Audio is perfectly in sync!",
    time: "8:40 PM",
  },
  {
    amountText: "$20.00",
    authorName: "Leo Park",
    id: "m4",
    kind: "paid",
    platform: "youtube",
    text: "Bought my first capture card because of this channel!",
    time: "8:41 PM",
  },
  {
    authorName: "kai.streams",
    firstMessage: true,
    id: "m5",
    platform: "twitch",
    text: "@nightowlstudio first time here, is this the Studio scene you built last week?",
    time: "8:41 PM",
  },
  {
    authorName: "Ana Silva",
    authorRoles: ["moderator"],
    id: "m6",
    platform: "youtube",
    reply: { authorName: "Maya Chen", text: "Which microphone are you using?" },
    text: "It's the Shure MV7, he said it last week.",
    time: "8:42 PM",
  },
  {
    authorName: "Sam Okafor",
    id: "m7",
    platform: "twitch",
    text: "What mic is that? Sounds great",
    time: "8:42 PM",
  },
  {
    authorName: "Hana Ito",
    id: "m8",
    platform: "x",
    text: "Can you show the scene setup again?",
    time: "8:43 PM",
  },
];

/** New chat while the window is open, one every few seconds. */
const ARRIVALS: Omit<ChatMessageData, "id" | "time">[] = [
  { authorName: "pixelpilot", platform: "twitch", text: "Raid squad says hi!" },
  {
    authorName: "Maya Chen",
    platform: "youtube",
    text: "The captions are so fast now.",
  },
  { authorName: "Priya Raman", platform: "x", text: "Clip that!" },
  {
    authorName: "nightowl_jonas",
    authorRoles: ["member"],
    platform: "twitch",
    text: "Fourteen months and the stream keeps getting better.",
  },
  {
    authorName: "Leo Park",
    platform: "youtube",
    text: "Will you put the overlay pack in the description?",
  },
];

/** Messages behind Buddy's open question: two people asking about the mic. */
const QUESTION_IDS = new Set(["m1", "m7"]);
const MENTION_NAMES = ["@nightowlstudio"];

const ACTIVITY: ActivityItem[] = [
  {
    id: "a1",
    kind: "super-chat",
    line: "Sent a $20.00 Super Chat",
    message: "Bought my first capture card because of this channel!",
    messageId: "m4",
    name: "Leo Park",
    platform: "youtube",
    short: "Super Chat · $20.00",
    time: "2m",
  },
  {
    id: "a2",
    kind: "subscription",
    line: "Resubscribed for 14 months at Tier 1",
    message: "Fourteen months of two-camera streams.",
    name: "nightowl_jonas",
    platform: "twitch",
    short: "Resub · 14 months",
    time: "4m",
  },
  {
    gift: true,
    id: "a3",
    kind: "subscription",
    line: "Gifted 5 Tier 1 subs to the community",
    name: "kai.streams",
    platform: "twitch",
    short: "Gifted 5 subs",
    time: "6m",
  },
  {
    id: "a4",
    kind: "raid",
    line: "Raided with 42 viewers",
    name: "pixelpilot",
    platform: "twitch",
    short: "Raid · 42 viewers",
    time: "9m",
  },
  {
    id: "a5",
    kind: "follow",
    line: "3 new followers on X",
    name: "3 new followers",
    platform: "x",
    short: "",
    time: "12m",
    unnamed: true,
  },
];

const COMMANDS: ChatComposerCommand[] = [
  {
    argument: true,
    hint: " [title] · Save a timeline point",
    value: "/marker",
  },
  { hint: " · Save the last 30 seconds as a clip", value: "/clip" },
  { hint: " · Save the last minute as a clip", value: "/clip 60" },
  { hint: " · Hide screen", value: "/hide" },
  { hint: " · Show screen", value: "/show" },
  { hint: " · Command help", value: "/help" },
];

// Stand-ins for the macOS traffic lights, which the OS draws in a real window.
const TrafficLights = () => (
  <div aria-hidden className="absolute top-3.5 left-5 z-10 flex gap-2">
    <span className="bg-foreground/20 size-3 rounded-full" />
    <span className="bg-foreground/20 size-3 rounded-full" />
    <span className="bg-foreground/20 size-3 rounded-full" />
  </div>
);

/** The Buddy pane, as this demo draws it: its header and one question card. */
const BuddyPane = ({ onShowQuestion }: { onShowQuestion: () => void }) => {
  const [answered, setAnswered] = useState(false);
  return (
    <div className="flex min-h-0 flex-1 flex-col">
      <div className="border-border flex min-h-9 shrink-0 items-center gap-2 border-b px-3 py-1">
        <span className="text-xs font-medium">Orcle</span>
        <Badge variant="outline">Alpha</Badge>
        <span className="flex-1" />
        <StatusDot label="Listening" pulse tone="good" />
      </div>
      <div className="flex flex-col gap-2 p-3">
        {answered ? (
          <p className="text-muted-foreground text-xs">
            Orcle reads chat during a live stream: questions, flags and the
            room&apos;s mood.
          </p>
        ) : (
          <Alert icon={SparkleIcon}>
            <AlertTitle>2 people asking</AlertTitle>
            <AlertDescription>
              Which microphone are you using on stream today?
            </AlertDescription>
            <div className="col-start-2 mt-1.5 flex flex-wrap gap-1">
              <Button onClick={onShowQuestion} size="xs" variant="secondary">
                Show on stream
              </Button>
              <Button
                onClick={() => setAnswered(true)}
                size="xs"
                variant="ghost"
              >
                Answered
              </Button>
            </div>
          </Alert>
        )}
      </div>
    </div>
  );
};

const nowTime = (): string =>
  new Date().toLocaleTimeString([], { hour: "numeric", minute: "2-digit" });

const StreamManagerDemo = () => {
  const [seconds, setSeconds] = useState(STARTED_SECONDS);
  const [messages, setMessages] = useState(MESSAGES);
  const [activity, setActivity] = useState(ACTIVITY);
  const [arrived, setArrived] = useState(0);
  const [highlight, setHighlight] = useState<StreamHighlight | null>({
    messageId: "m3",
    phase: "live",
  });
  const [layout, setLayout] = useState<StatsLayout>(DEFAULT_STATS_LAYOUT);
  const [pinned, setPinned] = useState(true);
  const [position, setPosition] = useState<HighlightPosition>("bottom-left");
  const [screenHidden, setScreenHidden] = useState(false);
  const [autoShow, setAutoShow] = useState(true);
  const [pending, setPending] = useState(false);
  const [notice, setNotice] = useState<string | null>(null);

  useEffect(() => {
    const timer = setInterval(() => setSeconds((value) => value + 1), TICK_MS);
    return () => clearInterval(timer);
  }, []);
  useEffect(() => {
    let count = 0;
    const timer = setInterval(() => {
      count += 1;
      const next = ARRIVALS[(count - 1) % ARRIVALS.length];
      setArrived(count);
      if (next) {
        setMessages((current) =>
          [...current, { ...next, id: `new-${count}`, time: nowTime() }].slice(
            -MOST_MESSAGES
          )
        );
      }
    }, ARRIVAL_MS);
    return () => clearInterval(timer);
  }, []);

  // A show takes a moment while Studio puts it on stream.
  const toggleOnStream = (messageId: string): void => {
    if (highlight?.messageId === messageId && highlight.phase === "live") {
      setHighlight(null);
      return;
    }
    setHighlight({ messageId, phase: "applying" });
    setTimeout(() => setHighlight({ messageId, phase: "live" }), APPLY_MS);
  };

  return (
    // The window and the stand-in traffic lights on its title row.
    <div className="relative h-[40rem] w-full">
      <TrafficLights />
      <StreamManager
        activity={activity}
        autoShow={autoShow}
        buddy={{
          name: "Orcle",
          pane: <BuddyPane onShowQuestion={() => toggleOnStream("m1")} />,
          tone: "good",
          toneLabel: "Buddy is listening",
          unseen: 1,
        }}
        className="rounded-panel h-full border"
        composerCommands={COMMANDS}
        composerNotice={notice}
        composerPlaceholder="Message, /marker [title] or /clip…"
        destinationNotes={{ x: ["X live chat reads only on this stream."] }}
        destinations={DESTINATIONS}
        highlight={highlight}
        highlightPosition={position}
        live
        mentionNames={MENTION_NAMES}
        messages={messages}
        onAutoShowChange={setAutoShow}
        onClear={() => {
          setMessages([]);
          setActivity([]);
          setHighlight(null);
        }}
        onComposerCommand={(command) =>
          setNotice(
            command.startsWith("/marker")
              ? `Marker saved at ${clock(seconds)} · ${command.slice(8).trim() || "Untitled marker"}`
              : "Saving the last 30 seconds as a clip…"
          )
        }
        onHighlight={(message) => toggleOnStream(message.id)}
        onHighlightPositionChange={setPosition}
        onMarkClip={(length) =>
          setNotice(
            length === 30
              ? "Saving the last 30 seconds as a clip…"
              : "Saving the last minute as a clip…"
          )
        }
        onOpenPreview={() => setNotice("The Preview window opens.")}
        onPinnedChange={setPinned}
        onScreenPrivacy={setScreenHidden}
        onSend={(text) => {
          setNotice(null);
          setPending(true);
          setTimeout(() => {
            setPending(false);
            setMessages((current) => [
              ...current,
              {
                authorName: "Night Owl Studio",
                authorRoles: ["owner"],
                id: `sent-${current.length}`,
                platform: "youtube",
                text,
                time: nowTime(),
              },
            ]);
          }, SEND_MS);
        }}
        onShowActivityOnStream={(item) =>
          item.messageId ? toggleOnStream(item.messageId) : undefined
        }
        onStatsLayoutChange={setLayout}
        pinned={pinned}
        platform="darwin"
        questionIds={QUESTION_IDS}
        screenHidden={screenHidden}
        sendPending={pending}
        stats={statItems(seconds, 18 + (arrived % 7))}
        statsLayout={layout}
        thankYouDraft={(item) => `Thank you, ${item.name}!`}
      />
    </div>
  );
};

export default StreamManagerDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/stream-manager
```

This installs every part with it: [Chat Message](/docs/blocks/chat-message), [Chat Toolbar](/docs/blocks/chat-toolbar), [Chat Composer](/docs/blocks/chat-composer), [Stream Stats Bar](/docs/blocks/stream-stats-bar), [Activity Feed](/docs/blocks/activity-feed) and [Stream Manager Status Bar](/docs/blocks/stream-manager-status-bar).

## Usage

```tsx
import { StreamManager } from "@/components/blocks/stream-manager/stream-manager";
```

```tsx
<StreamManager
  activity={activity}
  destinations={destinations}
  highlight={onStream}
  live
  messages={messages}
  onHighlight={toggleOnStream}
  onSend={send}
  platform={process.platform}
  stats={stats}
/>
```

The window is presentational: your app owns the session and passes it in as plain data, and every action comes back as a callback. Nothing reaches for Electron, IPC or `window.videorc`.

| Prop | The data |
| --- | --- |
| `stats` | `StatItem[]`: the clock, viewers, followers and the rest ([Stream Stats Bar](/docs/blocks/stream-stats-bar)) |
| `messages` | `ChatMessageData[]`, oldest first ([Chat Message](/docs/blocks/chat-message)) |
| `destinations` | `ChatDestination[]`: each platform's chat state and whether it sends ([Chat Platform](/docs/blocks/chat-platform)) |
| `activity` | `ActivityItem[]`: follows, subs, gifts, tips and raids ([Activity Feed](/docs/blocks/activity-feed)) |
| `highlight` | `{ messageId, phase }`: the message on stream, the one slot Chat and Activity share |
| `buddy` | `{ name, tone, unseen, pane }`: Buddy's tab and its pane, when there is one |

A row's click calls `onHighlight`, and the window shows whatever `highlight` you pass back: `applying` while Studio puts it on stream, then `live`, or `failed` with its reason.

## The window

- **Three tiers by its own width.** The body is `@container/stream-manager`, never the viewport. From 1,040 px Chat sits beside a right pane with Activity and Buddy tabs, and the stats bar draws its sparklines. From 640 px one pane sits behind Chat, Activity and Buddy tabs. Below 640 px (320 minimum) the filters and the status bar's controls fold into menus. Every pane renders once; only its placement changes. Give it any size: a window, a split pane or a docs preview.
- **The title row carries the title only.** The stats bar says ON AIR, and a finished session (`history`) gets its own bar with Back to live. Pass the `platform` you know so the row leaves room for the macOS traffic lights.
- **Live and not.** While `live`, a click puts a message on stream, the composer shows, and a row's time and ⋯ wait for the pointer. Off air, chat says how it starts and the rows are plain text.
- **Keys.** While focus is in the window, ⌘F searches chat, ⌘L writes in it and ⌘J brings Buddy forward. The status bar prints the same keys as clickable hints.
- **Replies and thanks fill the composer, never send.** A row's ⋯ Reply writes "@name ", and Activity's Thank in chat writes what `thankYouDraft` returns: the streamer sends.

## Examples

### History

Without `live` the window reads a session back: `history` adds its bar with Back to live, the stats are the session's totals, and the rows are plain text with their times. There's no composer, and an empty chat says how it starts.

```tsx title="components/examples/stream-manager-off-air.tsx"
"use client";

import type { ChatMessageData } from "@/components/blocks/stream-manager/chat-message";
import type { ChatDestination } from "@/components/blocks/stream-manager/chat-platform";
import { StreamManager } from "@/components/blocks/stream-manager/stream-manager";
import type { StatItem } from "@/components/blocks/stream-manager/stream-stats-bar";

const STATS: StatItem[] = [
  {
    badge: "history",
    description: "History: Building a two-camera podcast scene, Oct 29",
    details: [{ label: "Title", value: "Building a two-camera podcast scene" }],
    id: "session",
    label: "Session",
    tone: "neutral",
    value: "Oct 29",
  },
  {
    description: "Peak 1.4k viewers, average 1.1k",
    details: [
      { label: "Peak", value: "1.4k" },
      { label: "Average", value: "1.1k" },
    ],
    id: "viewers",
    label: "Viewers",
    tone: "neutral",
    unit: "peak",
    value: "1.4k",
  },
  {
    description: "2,318 messages, 412 chatters",
    details: [{ label: "Chatters", value: "412" }],
    id: "chat",
    label: "Chat",
    tone: "neutral",
    unit: "messages",
    value: "2,318",
  },
];

const DESTINATIONS: ChatDestination[] = [
  { id: "yt", platform: "youtube", state: "ended", write: "ready" },
  { id: "tw", platform: "twitch", state: "ended", write: "ready" },
];

const MESSAGES: ChatMessageData[] = [
  {
    authorName: "Maya Chen",
    id: "h1",
    platform: "youtube",
    text: "Which microphone are you using on stream today?",
    time: "8:39 PM",
  },
  {
    authorName: "nightowl_jonas",
    authorRoles: ["member"],
    id: "h2",
    platform: "twitch",
    text: "Great stream, see you Thursday!",
    time: "9:58 PM",
  },
];

const StreamManagerOffAir = () => (
  <StreamManager
    className="rounded-panel h-[26rem] w-full border"
    destinations={DESTINATIONS}
    history={{
      date: "Oct 29",
      onBackToLive: () => null,
      title: "Building a two-camera podcast scene",
    }}
    messages={MESSAGES}
    platform="win32"
    stats={STATS}
  />
);

export default StreamManagerOffAir;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `@container/stream-manager` | The window body; every part's tiers read it |
| `@min-[1040px]/stream-manager:` | Wide: Chat beside the right pane |
| `bg-glass-content` | The window's content coat (`WindowFrame`) |
| `data-pane` | `chat`, `activity`, `buddy` |
| `data-slot` | `stream-manager`, `stream-manager-panes`, `pane-tabs`, `pane-tabs-wide`, `chat-pane`, `history-bar` |

## Keyboard

| Key | Action |
| --- | --- |
| <kbd>⌘</kbd> <kbd>F</kbd> | Searches chat |
| <kbd>⌘</kbd> <kbd>L</kbd> | Writes in chat, while live |
| <kbd>⌘</kbd> <kbd>J</kbd> | Brings Buddy's pane forward |
| <kbd>Enter</kbd> <kbd>Space</kbd> | On a message, puts it on stream or takes it off |

On Windows and Linux the keys are Ctrl. They answer while focus is inside the window, so a page around it keeps its own.

## Accessibility

The title is the window's `h1`. The stats bar, Chat and Activity are named regions, and the pane tabs are a tab list; Buddy's dot says what it means through `buddy.toneLabel`, never colour alone. Each part brings its own: see their pages.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `"Stream Manager"` | — |
| `platform` | `string` | — | darwin, win32, linux… |
| `live` | `boolean` | `false` | A live session. |
| `history` | `{ title: string; date: string; onBackToLive?: () => void }` | — | A finished session, read back. |
| `stats` | `readonly StatItem[]` | — | — |
| `statsLayout` | `StatsLayout` | — | — |
| `onStatsLayoutChange` | `(layout: StatsLayout) => void` | — | — |
| `screenHidden` | `boolean` | `false` | — |
| `messages` | `readonly ChatMessageData[]` | — | — |
| `destinations` | `readonly ChatDestination[]` | — | — |
| `mentionNames` | `readonly string[]` | — | Your accounts: @you and Mentions. |
| `questionIds` | `ReadonlySet<string>` | — | Messages behind Buddy's open questions. |
| `highlight` | `{ messageId: string; phase: "applying" \| "live" \| "failed"; reason?: string } \| null` | — | The message on stream. |
| `onHighlight` | `(message) => void` | — | — |
| `removals` | `Record<string, ChatMessageRemoval>` | — | By message id. |
| `flags` | `Record<string, ChatMessageFlag>` | — | Buddy's flags, by message id. |
| `suggestedIds` | `ReadonlySet<string>` | — | — |
| `spotlightId` | `string \| null` | — | — |
| `onRemoveFromChat` | `(message) => void` | — | — |
| `onSend` | `(text, options) => void` | — | The composer shows while live. |
| `sendPending` | `boolean` | `false` | — |
| `sendFailures` | `readonly ChatSendFailure[]` | — | — |
| `onRetrySend` | `() => void` | — | — |
| `composerCommands` | `readonly ChatComposerCommand[]` | — | — |
| `onComposerCommand` | `(text: string) => void` | — | — |
| `composerNotice` | `ReactNode` | — | — |
| `composerPlaceholder` | `string` | — | — |
| `activity` | `readonly ActivityItem[]` | `[]` | — |
| `activityNote` | `string \| null` | — | — |
| `onShowActivityOnStream` | `(item) => void` | — | — |
| `thankYouDraft` | `(item) => string` | — | Adds Thank in chat. |
| `twitchNeeds` | `{ followNames?: boolean; bitsAndPoints?: boolean }` | — | — |
| `onReconnectTwitch` | `() => void` | — | — |
| `autoShow` | `boolean` | — | — |
| `onAutoShowChange` | `(on: boolean) => void` | — | — |
| `buddy` | `StreamManagerBuddy` | — | Buddy's tab and pane. |
| `unseen` | `{ chat?: number; activity?: number }` | — | Counts on the tabs. |
| `pinned` | `boolean` | — | — |
| `onPinnedChange` | `(pinned: boolean) => void` | — | — |
| `destinationNotes` | `Partial<Record<ChatPlatform, string[]>>` | — | — |
| `highlightPosition` | `HighlightPosition` | — | — |
| `onHighlightPositionChange` | `(position) => void` | — | — |
| `onMarkClip` | `(seconds: 30 \| 60) => void` | — | While live. |
| `onScreenPrivacy` | `(hidden: boolean) => void` | — | — |
| `banners` | `readonly StreamBanner[] \| null` | — | — |
| `onBanner` | `(action: BannerAction) => void` | — | — |
| `onClear` | `() => void` | — | — |
| `onOpenPreview` | `() => void` | — | — |

### StreamManagerBuddy

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | — | The Buddy's name, on its tab: "Orcle". |
| `tone` | `"good" \| "warn" \| "error" \| "neutral"` | `"neutral"` | Its presence: good while listening. |
| `toneLabel` | `string` | — | "Buddy is listening", read aloud. |
| `unseen` | `number` | — | New questions and cards behind the tab. |
| `pane` | `ReactNode` | — | The Buddy pane. |

# Stream Stats Bar (/docs/blocks/stream-stats-bar)

```tsx title="components/examples/stream-stats-bar-demo.tsx"
"use client";

import { useEffect, useState } from "react";

import {
  DEFAULT_STATS_LAYOUT,
  StreamStatsBar,
} from "@/components/blocks/stream-manager/stream-stats-bar";
import type {
  StatItem,
  StatsLayout,
} from "@/components/blocks/stream-manager/stream-stats-bar";

const STARTED_SECONDS = 30 * 60 + 44;
const SECONDS_PER_MINUTE = 60;
const SECONDS_PER_HOUR = 3600;
const TICK_MS = 1000;

/** "30:44", or "1:02:03" past the hour. */
const formatClock = (seconds: number): string => {
  const hours = Math.floor(seconds / SECONDS_PER_HOUR);
  const minutes = Math.floor((seconds % SECONDS_PER_HOUR) / SECONDS_PER_MINUTE);
  const rest = String(seconds % SECONDS_PER_MINUTE).padStart(2, "0");
  return hours > 0
    ? `${hours}:${String(minutes).padStart(2, "0")}:${rest}`
    : `${minutes}:${rest}`;
};

const statItems = (seconds: number): StatItem[] => [
  {
    badge: "live",
    description: `On air for ${formatClock(seconds)}`,
    details: [{ label: "Started", value: "8:12 PM" }],
    id: "session",
    label: "Session",
    tone: "neutral",
    value: formatClock(seconds),
  },
  {
    description: "1.2k viewers, peak 1.4k",
    details: [
      { label: "YouTube", platform: "youtube", value: "812" },
      { label: "Twitch", platform: "twitch", value: "356" },
      { label: "X", platform: "x", value: "64" },
      { label: "Peak", value: "1.4k" },
    ],
    id: "viewers",
    label: "Viewers",
    spark: [880, 940, 1010, 990, 1080, 1150, 1120, 1232],
    tone: "neutral",
    value: "1.2k",
  },
  {
    delta: "+12",
    description: "61,942 followers, +12 this stream",
    details: [
      {
        label: "YouTube subscribers",
        note: "+9 this stream",
        platform: "youtube",
        value: "48,310",
      },
      {
        label: "Twitch followers",
        note: "+3 this stream",
        platform: "twitch",
        value: "13,632",
      },
    ],
    id: "followers",
    label: "Followers",
    tone: "neutral",
    unit: "followers",
    value: "61,942",
  },
  {
    description: "8 new supporters this stream",
    details: [{ label: "New this stream", value: "8" }],
    id: "supporters",
    label: "Supporters this stream",
    tone: "neutral",
    unit: "supporters",
    value: "8",
  },
  {
    description: "Tips this stream: $20, 300 bits",
    details: [
      { label: "Super Chats (USD)", value: "$20" },
      { label: "Bits", value: "300" },
    ],
    id: "tips",
    label: "Tips this stream",
    tone: "neutral",
    value: "$20 · 300 bits",
  },
  {
    description: "22 messages a minute, 318 chatters",
    details: [
      { label: "Messages in the last minute", value: "22" },
      { label: "Chatters", value: "318" },
    ],
    id: "chat",
    label: "Chat",
    tone: "neutral",
    unit: "msg/min",
    value: "22",
  },
];

const StreamStatsBarDemo = () => {
  const [seconds, setSeconds] = useState(STARTED_SECONDS);
  const [layout, setLayout] = useState<StatsLayout>(DEFAULT_STATS_LAYOUT);
  useEffect(() => {
    const timer = setInterval(() => setSeconds((value) => value + 1), TICK_MS);
    return () => clearInterval(timer);
  }, []);
  return (
    // The Stream Manager's container: the bar's tiers follow its width.
    <div className="rounded-panel bg-glass-content @container/stream-manager w-full overflow-hidden border">
      <StreamStatsBar
        className="border-b-0"
        items={statItems(seconds)}
        layout={layout}
        onLayoutChange={setLayout}
      />
    </div>
  );
};

export default StreamStatsBarDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/stream-stats-bar
```

This adds `stream-stats-bar.tsx` and its sparkline, `stats-sparkline.tsx`, and installs `recharts`.

## Usage

```tsx
import {
  DEFAULT_STATS_LAYOUT,
  StreamStatsBar,
} from "@/components/blocks/stream-manager/stream-stats-bar";
import type { StatItem } from "@/components/blocks/stream-manager/stream-stats-bar";
```

```tsx
const items: StatItem[] = [
  {
    id: "session",
    label: "Session",
    value: "30:44",
    badge: "live",
    tone: "neutral",
    details: [{ label: "Started", value: "8:12 PM" }],
    description: "On air for 30:44",
  },
  {
    id: "viewers",
    label: "Viewers",
    value: "1.2k",
    tone: "neutral",
    spark: [880, 940, 1010, 1232],
    details: [{ label: "YouTube", value: "812", platform: "youtube" }],
    description: "1.2k viewers, peak 1.4k",
  },
];

<StreamStatsBar items={items} layout={layout} onLayoutChange={setLayout} />;
```

Each stat is plain data you compute: its value as shown, a unit, a change, a tone, its sparkline points and its hover card's rows. The bar never measures anything itself.

- **Never an unmeasured zero.** Give a stat only when its source exists for this session, and show "–" with the reason in its details when a number can't be read.
- **Quiet when fine.** Numbers stay monochrome and tabular. Tone lives in the session chip (ON AIR is the only emphasis) and in a stat's sparkline when it's in trouble.
- **Main slots first.** The first three stats in the layout are drawn larger and never clipped: by default the clock, viewers and followers. The rest follow after a hairline in a clipped, wrapping row, so a stat that doesn't fit drops off the end whole.

## Examples

### Off air, with the screen hidden

Off air the clock says so in the subtle tier. `screenHidden` closes the bar with the "Screen hidden" chip, which never moves a stat.

```tsx title="components/examples/stream-stats-bar-off-air.tsx"
"use client";

import { StreamStatsBar } from "@/components/blocks/stream-manager/stream-stats-bar";
import type { StatItem } from "@/components/blocks/stream-manager/stream-stats-bar";

// Off air, nothing is measured: the clock says so, and the chat pace shows
// "–" with the reason on hover, never a zero nobody counted.
const ITEMS: StatItem[] = [
  {
    badge: "off-air",
    description: "Off air",
    details: [],
    id: "session",
    label: "Session",
    tone: "subtle",
    value: "Off air",
  },
  {
    description: "Chat isn't connected",
    details: [
      {
        label: "Messages in the last minute",
        note: "Chat isn't connected",
        value: "–",
      },
    ],
    id: "chat",
    label: "Chat",
    tone: "subtle",
    value: "–",
  },
];

const StreamStatsBarOffAir = () => (
  <div className="rounded-panel bg-glass-content @container/stream-manager w-full max-w-md overflow-hidden border">
    <StreamStatsBar className="border-b-0" items={ITEMS} screenHidden />
  </div>
);

export default StreamStatsBarOffAir;
```

## Arranging stats

With `onLayoutChange`, the streamer drags a stat onto another to move it, and right-clicks the bar to show or hide stats, move the one under the pointer, or reset. The clock and the viewer count can't be hidden or leave the main slots: the viewer count is never hidden while live. Keep the layout per machine, as Videorc does in `localStorage`. Without `onLayoutChange` the order is fixed.

`arrangeStats`, `moveStat`, `setStatHidden` and `statsLayoutIsDefault` are the rules, and `STAT_NAMES` the stats' names, for a menu of your own (the [Stream Manager Status Bar](/docs/blocks/stream-manager-status-bar) folds the same choices into its ⋯ menu).

## Responsive

The sparklines are a Wide luxury: they appear when the `@container/stream-manager` around the bar is 1,040 px or wider. Below it the number is the reading. The examples here wrap the bar in that container; the [Stream Manager](/docs/blocks/stream-manager) is one.

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `Badge` `live` | ON AIR, the only emphasis |
| `text-subtle` | A reading that isn't live (`tone: "subtle"`) |
| `tabular-nums` | Every number |
| `@min-[1040px]/stream-manager:` | Where the sparklines appear |
| `StatusBadge` `warn` | Screen hidden |
| `data-stat`, `data-group`, `data-tone` | On each stat: its id, `main` or `more`, its tone |
| `data-slot` | `stream-stats-bar`, `stats-main`, `stats-more`, `stat-item`, `stat-value`, `stats-sparkline` |

## Accessibility

The bar is a region named "Stream stats". Each stat is one image named by its `description`, the whole reading in words, and a stat with details is a tab stop whose hover card also opens on focus. An arrangeable bar is a tab stop too, so its menu opens from the keyboard.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `readonly StatItem[]` | — | — |
| `layout` | `StatsLayout` | `DEFAULT_STATS_LAYOUT` | — |
| `onLayoutChange` | `(layout: StatsLayout) => void` | — | Lets the streamer drag and pick stats. Absent: a fixed order. |
| `screenHidden` | `boolean` | `false` | The screen is hidden from viewers: the chip closes the bar. |

### StatItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `"session" \| "viewers" \| "followers" \| "supporters" \| "tips" \| "chat"` | — | — |
| `label` | `string` | — | The hover card's heading. |
| `value` | `string` | — | The number as shown, or "–". |
| `unit` | `string` | — | "followers", "msg/min". |
| `delta` | `string` | — | "+12". |
| `tone` | `"neutral" \| "subtle" \| "good" \| "warning" \| "error"` | — | subtle dims it; warning and error tint its sparkline. |
| `badge` | `"live" \| "recording" \| "off-air" \| "history"` | — | The session's chip: ON AIR, Recording, History. |
| `spark` | `readonly number[]` | — | Sparkline points, oldest first. |
| `details` | `readonly StatDetailRow[]` | — | The hover card's rows: label, value, platform, note. |
| `description` | `string` | — | The whole reading in words. |

### StatsLayout

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `order` | `StatId[]` | — | Every stat in order; the first three are the main slots. |
| `hidden` | `StatId[]` | — | Stats the streamer hid. |

# Accordion (/docs/components/accordion)

```tsx title="components/examples/accordion-demo.tsx"
"use client";

import {
  Accordion,
  AccordionContent,
  AccordionItem,
  AccordionTrigger,
} from "@/components/ui/accordion";

const AccordionDemo = () => (
  <Accordion className="max-w-md" defaultValue={["video"]}>
    <AccordionItem value="video">
      <AccordionTrigger>Video</AccordionTrigger>
      <AccordionContent>
        Record at 1080p and 60 fps. Livestreams use the quality each destination
        accepts.
      </AccordionContent>
    </AccordionItem>
    <AccordionItem value="audio">
      <AccordionTrigger>Audio</AccordionTrigger>
      <AccordionContent>
        Your microphone and system audio are mixed into one track, with noise
        cleanup on.
      </AccordionContent>
    </AccordionItem>
    <AccordionItem value="output">
      <AccordionTrigger>Output</AccordionTrigger>
      <AccordionContent>
        Recordings save as MP4 to your Movies folder.
      </AccordionContent>
    </AccordionItem>
  </Accordion>
);

export default AccordionDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/accordion
```

## Usage

```tsx
import {
  Accordion,
  AccordionContent,
  AccordionItem,
  AccordionTrigger,
} from "@/components/ui/accordion";
```

```tsx
<Accordion defaultValue={["video"]}>
  <AccordionItem value="video">
    <AccordionTrigger>Video</AccordionTrigger>
    <AccordionContent>Record at 1080p and 60 fps.</AccordionContent>
  </AccordionItem>
</Accordion>
```

## Anatomy

```tsx
<Accordion>
  <AccordionItem>
    <AccordionTrigger />
    <AccordionContent />
  </AccordionItem>
</Accordion>
```

## Examples

### Multiple

Set `multiple` to let several items stay open, as the Go Live details for each destination do. The value is always an array, open or closed, single or multiple.

```tsx title="components/examples/accordion-multiple.tsx"
"use client";

import { useState } from "react";

import {
  Accordion,
  AccordionContent,
  AccordionItem,
  AccordionTrigger,
} from "@/components/ui/accordion";

const DESTINATIONS = [
  {
    details: "Public, not made for kids. Title: Launch day.",
    label: "YouTube",
    value: "youtube",
  },
  {
    details: "Category: Science & Technology. Title: Launch day.",
    label: "Twitch",
    value: "twitch",
  },
  {
    details: "Posts the stream link when you go live.",
    label: "X",
    value: "x",
  },
];

const AccordionMultiple = () => {
  const [open, setOpen] = useState<string[]>(["youtube", "twitch"]);
  return (
    <Accordion
      aria-label="Details for each destination"
      className="max-w-md"
      multiple
      onValueChange={setOpen}
      value={open}
    >
      {DESTINATIONS.map((destination) => (
        <AccordionItem key={destination.value} value={destination.value}>
          <AccordionTrigger>{destination.label}</AccordionTrigger>
          <AccordionContent>{destination.details}</AccordionContent>
        </AccordionItem>
      ))}
    </Accordion>
  );
};

export default AccordionMultiple;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `rounded-row`, `border` | The group: the 8 px row radius and one hairline |
| `data-open` | On an open item, which takes a `bg-muted/50` wash |
| `data-panel-open` | On the trigger of an open item; swaps the chevron |
| `--accordion-panel-height` | The panel's measured height, eased in 150 ms with `data-starting-style` and `data-ending-style` |
| `data-disabled` | On a disabled item and its trigger |

## Keyboard

| Key                               | Action                           |
| --------------------------------- | -------------------------------- |
| <kbd>Tab</kbd>                    | Moves to the next trigger        |
| <kbd>Enter</kbd> <kbd>Space</kbd> | Opens or closes the focused item |

## Accessibility

Each trigger is a button inside a heading, with `aria-expanded` and `aria-controls` pointing at its panel. Name the group when it has a job of its own (`aria-label="Details for each destination"`).

## API reference

### Accordion

Every [Base UI Accordion](https://base-ui.com/react/components/accordion) Root prop. The ones that differ from Radix:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `multiple` | `boolean` | `false` | Lets several items stay open; replaces type="multiple". |
| `value` | `Value[]` | — | The open items, always an array. |
| `defaultValue` | `Value[]` | — | The items open at first. |
| `onValueChange` | `(value: Value[], eventDetails) => void` | — | — |

`AccordionItem` takes a `value`; `AccordionTrigger` and `AccordionContent` take every Base UI Trigger and Panel prop, and `AccordionContent`'s `className` styles its inner padding box.

# Alert Dialog (/docs/components/alert-dialog)

```tsx title="components/examples/alert-dialog-demo.tsx"
"use client";

import { useState } from "react";

import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogTrigger,
} from "@/components/ui/alert-dialog";
import { Button } from "@/components/ui/button";

const AlertDialogDemo = () => {
  const [open, setOpen] = useState(false);
  return (
    <AlertDialog onOpenChange={setOpen} open={open}>
      <AlertDialogTrigger render={<Button variant="destructive" />}>
        Delete scene…
      </AlertDialogTrigger>
      <AlertDialogContent>
        <AlertDialogHeader>
          <AlertDialogTitle>Delete saved scene?</AlertDialogTitle>
          <AlertDialogDescription>
            Only the saved snapshot is deleted. Your current scene and recording
            continue.
          </AlertDialogDescription>
        </AlertDialogHeader>
        <AlertDialogFooter>
          <AlertDialogCancel>Cancel</AlertDialogCancel>
          <AlertDialogAction
            onClick={() => setOpen(false)}
            variant="destructive"
          >
            Delete scene
          </AlertDialogAction>
        </AlertDialogFooter>
      </AlertDialogContent>
    </AlertDialog>
  );
};

export default AlertDialogDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/alert-dialog
```

## Usage

```tsx
import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogTitle,
} from "@/components/ui/alert-dialog";
```

```tsx
<AlertDialog onOpenChange={setOpen} open={open}>
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>Delete saved scene?</AlertDialogTitle>
      <AlertDialogDescription>
        Only the saved snapshot is deleted. Your current scene and recording
        continue.
      </AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>Cancel</AlertDialogCancel>
      <AlertDialogAction onClick={deleteScene} variant="destructive">
        Delete scene
      </AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>
```

The title is "Verb object?", and one sentence names exactly what is lost. The safe answer ("Cancel", or "Keep …") is a ghost button; the destructive one reads verb and object. A consequential step that destroys nothing, such as a replace, keeps `variant="default"`.

## Anatomy

```tsx
<AlertDialog>
  <AlertDialogTrigger />
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle />
      <AlertDialogDescription />
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel />
      <AlertDialogAction />
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>
```

## Examples

### Pending action

`AlertDialogAction` doesn't close the dialog: the owner drops `open` once the action is done. While async work runs, the dialog stays up and says so ("Deleting…"), and the answers are disabled.

```tsx title="components/examples/alert-dialog-pending.tsx"
"use client";

import { useState } from "react";

import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogTrigger,
} from "@/components/ui/alert-dialog";
import { Button } from "@/components/ui/button";

const DELETE_TAKES_MS = 1500;

const AlertDialogPending = () => {
  const [open, setOpen] = useState(false);
  const [deleting, setDeleting] = useState(false);

  // The dialog stays up, saying "Deleting…", until the work is done: then
  // the owner closes it.
  const confirm = () => {
    setDeleting(true);
    setTimeout(() => {
      setDeleting(false);
      setOpen(false);
    }, DELETE_TAKES_MS);
  };

  return (
    <AlertDialog
      onOpenChange={(next) => {
        if (!deleting) {
          setOpen(next);
        }
      }}
      open={open}
    >
      <AlertDialogTrigger render={<Button variant="destructive" />}>
        Delete recording…
      </AlertDialogTrigger>
      <AlertDialogContent>
        <AlertDialogHeader>
          <AlertDialogTitle>Delete recording?</AlertDialogTitle>
          <AlertDialogDescription>
            The recording and its markers move to the Trash.
          </AlertDialogDescription>
        </AlertDialogHeader>
        <AlertDialogFooter>
          <AlertDialogCancel disabled={deleting}>Cancel</AlertDialogCancel>
          <AlertDialogAction
            disabled={deleting}
            onClick={confirm}
            variant="destructive"
          >
            {deleting ? "Deleting…" : "Delete recording"}
          </AlertDialogAction>
        </AlertDialogFooter>
      </AlertDialogContent>
    </AlertDialog>
  );
};

export default AlertDialogPending;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `dialogContentVariants({ size })` | The same surface, widths and height rule as [Dialog](/docs/components/dialog) |
| `data-size` | `sm`, `md` (the default), `lg` or `xl` |
| `bg-black/30` | The overlay, with no backdrop blur |

## Keyboard

| Key                | Action                                        |
| ------------------ | --------------------------------------------- |
| `Escape`           | Closes the dialog: the same answer as Cancel  |
| `Tab`, `Shift+Tab` | Moves between the answers; focus stays inside |
| `Enter`, `Space`   | Presses the focused answer                    |

## Accessibility

The dialog is an `alertdialog`, named by its title and described by its description. Cancel has focus on open, even when the body holds a control before it, so a stray `Enter` or `Space` never destroys anything. A click outside doesn't close it.

## API reference

Every [Base UI Alert Dialog](https://base-ui.com/react/components/alert-dialog) prop, plus:

### AlertDialogContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | — |
| `initialFocus` | `boolean \| RefObject \| (openType) => HTMLElement \| boolean \| void` | — | Defaults to the dialog's Cancel. |

### AlertDialogAction

A [Button](/docs/components/button) that doesn't close the dialog.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `Button variant` | `"default"` | — |
| `size` | `Button size` | `"default"` | — |

### AlertDialogCancel

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `Button variant` | `"ghost"` | — |
| `size` | `Button size` | `"default"` | — |

# Alert (/docs/components/alert)

```tsx title="components/examples/alert-demo.tsx"
"use client";

import {
  Alert,
  AlertAction,
  AlertDescription,
  AlertTitle,
} from "@/components/ui/alert";
import { Button } from "@/components/ui/button";

const AlertDemo = () => (
  <Alert className="max-w-md" variant="warning">
    <AlertTitle>Stream health is poor</AlertTitle>
    <AlertDescription>
      Viewers may see buffering. Lower the bitrate or check your upload speed.
    </AlertDescription>
    <AlertAction>
      <Button size="xs" variant="secondary">
        Open Health
      </Button>
    </AlertAction>
  </Alert>
);

export default AlertDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/alert
```

## Usage

```tsx
import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert";
```

```tsx
<Alert variant="warning">
  <AlertTitle>Your microphone is muted.</AlertTitle>
</Alert>
```

## Anatomy

```tsx
<Alert>
  <AlertTitle />
  <AlertDescription />
  <AlertAction />
</Alert>
```

## Examples

### Variants

The variant is the tone. `default` and `quiet` are notes (`quiet` in secondary text), `locked` says why the controls under it are off, and `success`, `warning` and `destructive` report an outcome. A title alone reads as a message in regular weight; over a description it becomes a heading in medium.

```tsx title="components/examples/alert-variants.tsx"
"use client";

import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert";

const AlertVariants = () => (
  <div className="flex w-full max-w-md flex-col gap-2">
    <Alert>
      <AlertTitle>Recordings save to your Movies folder.</AlertTitle>
    </Alert>
    <Alert variant="quiet">
      <AlertTitle>Captions appear after the recording stops.</AlertTitle>
    </Alert>
    <Alert variant="locked">
      <AlertTitle>Locked while you’re recording or live.</AlertTitle>
      <AlertDescription>
        Changes apply the next time you record or go live.
      </AlertDescription>
    </Alert>
    <Alert variant="success">
      <AlertTitle>Recording saved</AlertTitle>
      <AlertDescription>Launch demo is in your library.</AlertDescription>
    </Alert>
    <Alert variant="warning">
      <AlertTitle>Your microphone is muted.</AlertTitle>
    </Alert>
    <Alert variant="destructive">
      <AlertTitle>Couldn’t save the recording</AlertTitle>
      <AlertDescription>
        The disk is full. Free up space, then record again.
      </AlertDescription>
    </Alert>
  </div>
);

export default AlertVariants;
```

### Icon

Each tone brings one glyph in one weight. Pass `icon` to show the subject's own mark instead (the microphone, a platform), or `icon={null}` for none. Never put an icon in the children.

```tsx title="components/examples/alert-icon.tsx"
"use client";

import { MicrophoneIcon } from "@/components/icons";
import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert";

const AlertIcon = () => (
  <div className="flex w-full max-w-md flex-col gap-2">
    <Alert icon={MicrophoneIcon} variant="warning">
      <AlertTitle>No microphone found</AlertTitle>
      <AlertDescription>
        Connect a microphone, or choose one in Sources.
      </AlertDescription>
    </Alert>
    <Alert icon={null} variant="quiet">
      <AlertTitle>Twitch shows your stream title above the chat.</AlertTitle>
    </Alert>
  </div>
);

export default AlertIcon;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `rounded-row` | The 8 px row radius; no border and no shadow |
| `bg-foreground/4` | The tint of `default`, `quiet` and `locked` |
| `bg-success/10`, `bg-warning/10`, `bg-destructive/10` | The tone tints; the icon takes the tone colour, the text stays monochrome |
| `data-variant` | The tone, for styling a part from the alert with `group-data-[variant=…]/alert` |
| `data-slot="alert-icon"` | The leading icon |

## Accessibility

A `destructive` alert is `role="alert"` and is announced at once. Every other tone is `role="status"`, a polite live region. Pass `role` to override it, for a card that is a group or a note that should stay silent. The icon is `aria-hidden`: the title carries the meaning.

## API reference

### Alert

Every `<div>` prop, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "quiet" \| "locked" \| "success" \| "warning" \| "destructive"` | `"default"` | The tone: the tint, the icon and the role. |
| `icon` | `AppIcon \| null` | — | Replaces the tone's icon; null drops it. |
| `role` | `AriaRole` | `"status"` | "alert" when the variant is destructive. |

`AlertTitle`, `AlertDescription` and `AlertAction` take every `<div>` prop. `AlertAction` sits in the top-right corner, and the alert pads its text to make room.

# Avatar (/docs/components/avatar)

```tsx title="components/examples/avatar-demo.tsx"
"use client";

import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";

const AvatarDemo = () => (
  <div className="flex items-center gap-3">
    <Avatar size="lg">
      <AvatarImage alt="Videorc" src="/brand/logo.png" />
      <AvatarFallback>VR</AvatarFallback>
    </Avatar>
    <Avatar>
      <AvatarFallback>MC</AvatarFallback>
    </Avatar>
    <Avatar size="sm">
      <AvatarFallback>JD</AvatarFallback>
    </Avatar>
  </div>
);

export default AvatarDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/avatar
```

## Usage

```tsx
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
```

```tsx
<Avatar>
  <AvatarImage alt="" src={authorAvatarUrl} />
  <AvatarFallback>MC</AvatarFallback>
</Avatar>
```

## Anatomy

```tsx
<Avatar>
  <AvatarImage />
  <AvatarFallback />
  <AvatarBadge />
</Avatar>

<AvatarGroup>
  <Avatar />
  <AvatarGroupCount />
</AvatarGroup>
```

## Examples

### Group

Overlap a few avatars and end with a count for the rest, such as a channel's moderators.

```tsx title="components/examples/avatar-group.tsx"
"use client";

import {
  Avatar,
  AvatarFallback,
  AvatarGroup,
  AvatarGroupCount,
} from "@/components/ui/avatar";

const MODERATORS = [
  { id: "maya", initials: "MC" },
  { id: "jonas", initials: "JD" },
  { id: "priya", initials: "PS" },
];

const AvatarGroupExample = () => (
  <AvatarGroup>
    {MODERATORS.map((moderator) => (
      <Avatar key={moderator.id}>
        <AvatarFallback>{moderator.initials}</AvatarFallback>
      </Avatar>
    ))}
    <AvatarGroupCount>+12</AvatarGroupCount>
  </AvatarGroup>
);

export default AvatarGroupExample;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `data-size` | `sm` (24 px), `default` (32 px) or `lg` (40 px) |
| `after:border-border` | The hairline over the picture, blended so it reads on any photo |
| `bg-muted`, `text-muted-foreground` | The fallback's fill and initials |

## Accessibility

Give `AvatarImage` an `alt` that names the person or channel. When the name is printed beside the avatar, as it is in a chat row, use `alt=""` and `aria-hidden` on the avatar so the name isn't read twice.

## API reference

### Avatar

Every [Base UI Avatar](https://base-ui.com/react/components/avatar) Root prop, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"default" \| "sm" \| "lg"` | `"default"` | — |

### AvatarFallback

Every Base UI Avatar Fallback prop. `delay` waits that many milliseconds before showing the initials, so a fast image never flashes them.

`AvatarBadge`, `AvatarGroup` and `AvatarGroupCount` take `<span>` and `<div>` props.

# Badge (/docs/components/badge)

```tsx title="components/examples/badge-demo.tsx"
"use client";

import { Badge } from "@/components/ui/badge";

const BadgeDemo = () => (
  <div className="flex flex-wrap items-center gap-2">
    <Badge variant="live">On air</Badge>
    <Badge variant="success">Connected</Badge>
    <Badge variant="outline">9:16</Badge>
    <Badge>1080p60</Badge>
  </div>
);

export default BadgeDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/badge
```

## Usage

```tsx
import { Badge } from "@/components/ui/badge";
```

```tsx
<Badge variant="success">Connected</Badge>
```

## Examples

### Variants

`default` is neutral glass and `outline` is a tag (9:16, counts, Beta) in secondary text. `success`, `warning` and `neutral` are status chips. `destructive` and `live` tint the glass, only for failed, on air and destructive. `chrome` is a highlight's On stream, `plate` a member's chip, and `ghost` a borderless word.

```tsx title="components/examples/badge-variants.tsx"
"use client";

import { Badge } from "@/components/ui/badge";

const BadgeVariants = () => (
  <div className="flex max-w-md flex-wrap items-center justify-center gap-2">
    <Badge>1080p60</Badge>
    <Badge variant="outline">Beta</Badge>
    <Badge variant="success">Connected</Badge>
    <Badge variant="warning">Reconnecting</Badge>
    <Badge variant="neutral">Idle</Badge>
    <Badge variant="destructive">Failed</Badge>
    <Badge variant="live">On air</Badge>
    <Badge variant="chrome">On stream</Badge>
    <Badge variant="plate">Member</Badge>
    <Badge variant="ghost">Draft</Badge>
  </div>
);

export default BadgeVariants;
```

### Status

A status chip carries its tone in a 6 px dot with a halo and a soft glow. A leading icon marked `data-icon="inline-start"` replaces the dot and takes the tone. The word is a human, sentence-case state ("Reconnecting"), never a raw value.

```tsx title="components/examples/badge-status.tsx"
"use client";

import { CheckIcon, WarningIcon } from "@/components/icons";
import { Badge } from "@/components/ui/badge";
import { Spinner } from "@/components/ui/spinner";

const BadgeStatus = () => (
  <div className="flex flex-col items-center gap-3">
    <div className="flex flex-wrap items-center gap-2">
      <Badge variant="success">Connected</Badge>
      <Badge variant="warning">Reconnecting</Badge>
      <Badge variant="neutral">Idle</Badge>
    </div>
    <div className="flex flex-wrap items-center gap-2">
      <Badge variant="success">
        <CheckIcon data-icon="inline-start" weight="bold" />
        Saved
      </Badge>
      <Badge variant="warning">
        <WarningIcon data-icon="inline-start" weight="fill" />
        Dropped frames
      </Badge>
      <Badge variant="neutral">
        <Spinner aria-hidden data-icon="inline-start" />
        Uploading
      </Badge>
    </div>
  </div>
);

export default BadgeStatus;
```

### As a button

Render another element with `render` when the chip is the control, as the chat's jump-to-latest chip is. A badge isn't a Base UI button, so no `nativeButton` is needed.

```tsx title="components/examples/badge-render.tsx"
"use client";

import { useState } from "react";

import { ArrowDownIcon } from "@/components/icons";
import { Badge } from "@/components/ui/badge";

const BadgeRender = () => {
  const [unread, setUnread] = useState(12);
  return (
    <Badge
      // oxlint-disable-next-line jsx-a11y/control-has-associated-label -- Base UI renders the label into it.
      render={<button onClick={() => setUnread(0)} type="button" />}
    >
      {unread > 0 ? `${unread} new` : "Latest"}
      <ArrowDownIcon data-icon="inline-end" />
    </Badge>
  );
};

export default BadgeRender;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `glass-chip` | The neutral glass: a gradient fill, a 1 px rim, a top highlight and a soft drop |
| `glass-chip-tinted` | The emphasis glass, tinted by the tone |
| `tone-success`, `tone-warning`, `tone-neutral`, `tone-destructive`, `tone-live` | Set `--chip-tone` for the dot, the leading icon or the tint |
| `glass-dot` | The status dot, drawn by the chip's `::before` |
| `chrome-fill`, `chrome-plate` | The `chrome` and `plate` chips |
| `rounded-tag` | The 7 px tag radius, between chip and row |
| `data-variant`, `data-slot="badge"` | The variant, for styling from a parent |

## Accessibility

A badge isn't focusable, so a `title` on it never reaches the keyboard or a screen reader. To explain a chip, wrap it in [Info tooltip](/docs/components/info-tooltip). A chip rendered as a `<button>` needs a name that says what it does when its word alone doesn't.

## API reference

Every [Base UI `useRender`](https://base-ui.com/react/utils/use-render) prop for a `<span>`, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "outline" \| "success" \| "warning" \| "neutral" \| "destructive" \| "live" \| "chrome" \| "plate" \| "ghost"` | `"default"` | — |
| `render` | `ReactElement \| (props, state) => ReactElement` | — | Replaces the rendered span. |

`badgeVariants({ variant })` returns the classes, for an element styled as a badge.

# Button (/docs/components/button)

```tsx title="components/examples/button-demo.tsx"
"use client";

import { RecordIcon } from "@/components/icons";
import { Button } from "@/components/ui/button";

const ButtonDemo = () => (
  <div className="flex flex-wrap items-center gap-2">
    <Button variant="record">
      <RecordIcon data-icon="inline-start" weight="fill" />
      Record
    </Button>
    <Button>Go Live…</Button>
    <Button variant="secondary">Open Stream Manager</Button>
    <Button variant="ghost">Cancel</Button>
  </div>
);

export default ButtonDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/button
```

## Usage

```tsx
import { Button } from "@/components/ui/button";
```

```tsx
<Button>Go Live…</Button>
```

## Examples

### Variants

`default` is the one chrome fill on a surface: the primary action. `secondary` is the everyday button, a glass chip. `ghost` sits in toolbars and rows, `outline` beside a field, and `destructive` deletes.

```tsx title="components/examples/button-variants.tsx"
"use client";

import { Button } from "@/components/ui/button";

const ButtonVariants = () => (
  <div className="flex flex-wrap items-center gap-2">
    <Button>Default</Button>
    <Button variant="secondary">Secondary</Button>
    <Button variant="outline">Outline</Button>
    <Button variant="ghost">Ghost</Button>
    <Button variant="destructive">Delete</Button>
    <Button variant="link">Link</Button>
    <Button variant="solid">Solid</Button>
    <Button variant="chromatic">Chromatic</Button>
  </div>
);

export default ButtonVariants;
```

### Chromatic and solid

Two more fills for when the chrome default isn't the right voice. `solid` is the regular button: a flat fill in the primary ink, with no chrome. `chromatic` is a face of the theme's solid in a 2px ring of liquid chrome: bands of silver flow around the ring, glints run against them, and hover surges the flow.

`chromatic` is always moving, so give it one moment on a screen, not every button. Under reduced motion, the ring's metal holds still.

```tsx title="components/examples/button-styles.tsx"
import { SparkleIcon } from "@/components/icons";
import { Button } from "@/components/ui/button";

const ButtonStyles = () => (
  <div className="flex flex-wrap items-center gap-3">
    <Button size="lg" variant="chromatic">
      <SparkleIcon data-icon="inline-start" weight="fill" />
      Go Live…
    </Button>
    <Button size="lg" variant="solid">
      Save scene
    </Button>
  </div>
);

export default ButtonStyles;
```

### Sizes

Every control is 28 px tall. `xs` and `icon-xs` (24 px) are for dense rows only; `lg` (32 px) is for a dialog's or a card's single call to action.

```tsx title="components/examples/button-sizes.tsx"
"use client";

import { MoreIcon, SettingsIcon } from "@/components/icons";
import { Button } from "@/components/ui/button";

const ButtonSizes = () => (
  <div className="flex flex-wrap items-center gap-2">
    <Button size="xs" variant="secondary">
      Extra small
    </Button>
    <Button variant="secondary">Default</Button>
    <Button size="lg" variant="secondary">
      Large
    </Button>
    <Button aria-label="Settings" size="icon" variant="ghost">
      <SettingsIcon />
    </Button>
    <Button aria-label="More actions" size="icon-xs" variant="ghost">
      <MoreIcon weight="bold" />
    </Button>
  </div>
);

export default ButtonSizes;
```

### Record

`record` is for Record and its stop button, nothing else: metallic red, polished like the default's chrome. Set `data-lit` while a recording or livestream runs, and it turns the brand red and its glow breathes. Delete stays `destructive`.

For the whole control, with its glyph, its words and the starting and stopping states, use [Record Button](/docs/primitives/record-button).

```tsx title="components/examples/button-record.tsx"
"use client";

import { useState } from "react";

import { RecordIcon, StopIcon } from "@/components/icons";
import { Button } from "@/components/ui/button";

const ButtonRecord = () => {
  const [recording, setRecording] = useState(false);
  return (
    <Button
      data-lit={recording ? "" : undefined}
      onClick={() => setRecording((value) => !value)}
      variant="record"
    >
      {recording ? (
        <StopIcon data-icon="inline-start" weight="fill" />
      ) : (
        <RecordIcon data-icon="inline-start" weight="fill" />
      )}
      {recording ? "Stop recording" : "Record"}
    </Button>
  );
};

export default ButtonRecord;
```

### As a link

A link that looks like a button is still a link: put `buttonVariants()` on a plain `<a>`. Rendering an `<a>` through `render` with `nativeButton={false}` keeps Base UI's button behaviour and adds `role="button"`, which is right only for an element that acts like a button.

```tsx title="components/examples/button-link.tsx"
"use client";

import { ExternalLinkIcon } from "@/components/icons";
import { buttonVariants } from "@/components/ui/button";

const ButtonLink = () => (
  <a
    className={buttonVariants({ variant: "outline" })}
    href="https://videorc.com"
    rel="noopener noreferrer"
    target="_blank"
  >
    Open videorc.com
    <ExternalLinkIcon data-icon="inline-end" />
  </a>
);

export default ButtonLink;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `chrome-fill` | The default fill: polished silver in dark, graphite in light |
| `chrome-led` | Record's metallic red, lit by `data-lit`, with a `--chrome-led-glow` glow |
| `chrome-chromatic` | The chromatic ring: `--chrome-chromatic-bands` of metal around `--chrome-chromatic-face-stops` |
| `glass-chip` | The secondary fill |
| `h-control`, `size-control` | The 28 px desktop control height |
| `data-variant`, `data-size` | The variant and size, for styling from a parent |

## Accessibility

An icon-only button needs an `aria-label`. Icons inside a labelled button are decorative; mark their position with `data-icon="inline-start"` or `"inline-end"` so the padding adjusts. Disabled buttons take no hover, so explain why with [Disabled reason](/docs/components/disabled-reason).

## API reference

Every [Base UI Button](https://base-ui.com/react/components/button) prop, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "secondary" \| "outline" \| "ghost" \| "destructive" \| "link" \| "record" \| "solid" \| "chromatic"` | `"default"` | — |
| `size` | `"default" \| "xs" \| "lg" \| "icon" \| "icon-xs"` | `"default"` | — |
| `render` | `ReactElement \| (props, state) => ReactElement` | — | Replaces the rendered element. |
| `nativeButton` | `boolean` | `true` | Set to false when render is not a button. |

`buttonVariants({ variant, size })` returns the classes, for a link or any element styled as a button.

# Chart (/docs/components/chart)

```tsx title="components/examples/chart-demo.tsx"
"use client";

import {
  Area,
  AreaChart,
  CartesianGrid,
  ReferenceLine,
  XAxis,
  YAxis,
} from "recharts";

import {
  ChartContainer,
  ChartTooltip,
  ChartTooltipContent,
} from "@/components/ui/chart";
import type { ChartConfig } from "@/components/ui/chart";

const TARGET_KBPS = 6000;

// The outgoing bitrate over the first hour of a livestream: steady at the
// target, with one dip when the network dropped.
const BITRATE = [
  { kbps: 6010, time: "0:00" },
  { kbps: 5980, time: "0:05" },
  { kbps: 6040, time: "0:10" },
  { kbps: 5990, time: "0:15" },
  { kbps: 6020, time: "0:20" },
  { kbps: 5210, time: "0:25" },
  { kbps: 3870, time: "0:30" },
  { kbps: 4960, time: "0:35" },
  { kbps: 5940, time: "0:40" },
  { kbps: 6010, time: "0:45" },
  { kbps: 6030, time: "0:50" },
  { kbps: 6000, time: "0:55" },
];

// Neutral: the chrome is monochrome, and a steady stream is nothing to flag.
const config = {
  kbps: { color: "var(--foreground)", label: "Bitrate (kbps)" },
} satisfies ChartConfig;

const ChartDemo = () => (
  <ChartContainer className="aspect-auto h-56 w-full max-w-lg" config={config}>
    <AreaChart data={BITRATE} margin={{ left: 0, right: 8, top: 8 }}>
      <CartesianGrid vertical={false} />
      <XAxis axisLine={false} dataKey="time" tickLine={false} tickMargin={8} />
      <YAxis
        axisLine={false}
        domain={[0, 8000]}
        tickFormatter={(value: number) => `${value / 1000}K`}
        tickLine={false}
        ticks={[0, 2000, 4000, 6000, 8000]}
        width={32}
      />
      <ChartTooltip
        content={<ChartTooltipContent indicator="line" />}
        cursor={false}
      />
      <ReferenceLine
        label={{
          fill: "var(--muted-foreground)",
          position: "insideBottomLeft",
          value: "Target",
        }}
        y={TARGET_KBPS}
      />
      <Area
        dataKey="kbps"
        fill="var(--color-kbps)"
        fillOpacity={0.1}
        stroke="var(--color-kbps)"
        strokeWidth={2}
        type="monotone"
      />
    </AreaChart>
  </ChartContainer>
);

export default ChartDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/chart
```

## Usage

```tsx
import { Area, AreaChart } from "recharts";

import {
  ChartContainer,
  ChartTooltip,
  ChartTooltipContent,
} from "@/components/ui/chart";
import type { ChartConfig } from "@/components/ui/chart";
```

```tsx
const config = {
  kbps: { color: "var(--foreground)", label: "Bitrate (kbps)" },
} satisfies ChartConfig;

<ChartContainer className="aspect-auto h-56" config={config}>
  <AreaChart data={data}>
    <ChartTooltip content={<ChartTooltipContent />} />
    <Area dataKey="kbps" fill="var(--color-kbps)" stroke="var(--color-kbps)" />
  </AreaChart>
</ChartContainer>;
```

Every key in the config becomes a `--color-<key>` variable on the chart, per theme. Point a mark's `fill` and `stroke` at it.

## Anatomy

```tsx
<ChartContainer config={config}>
  <AreaChart>
    <ChartTooltip content={<ChartTooltipContent />} />
    <ChartLegend content={<ChartLegendContent />} />
  </AreaChart>
</ChartContainer>
```

## Examples

### Sparklines

A stats sparkline has no axes, no tooltip and no animation: the number above it is the reading. It's neutral by default and takes the warning tone only when the tile itself is a warning, with an icon beside its label so the colour is never alone.

```tsx title="components/examples/chart-sparkline.tsx"
"use client";

import { Area, AreaChart, YAxis } from "recharts";

import { WarningIcon } from "@/components/icons";
import { ChartContainer } from "@/components/ui/chart";
import type { ChartConfig } from "@/components/ui/chart";

const neutral = {
  value: { color: "var(--muted-foreground)", label: "Value" },
} satisfies ChartConfig;

// Colour only when the tile itself is a warning.
const warning = {
  value: { color: "var(--warning)", label: "Value" },
} satisfies ChartConfig;

const toPoints = (values: number[]) =>
  values.map((value, index) => ({ index, value }));

const Sparkline = ({
  config,
  values,
}: {
  config: ChartConfig;
  values: number[];
}) => (
  // No axes, no tooltip, no animation: the number above it is the reading.
  <ChartContainer
    aria-hidden
    className="aspect-auto h-6 w-full"
    config={config}
    initialDimension={{ height: 24, width: 120 }}
  >
    <AreaChart
      data={toPoints(values)}
      margin={{ bottom: 0, left: 0, right: 0, top: 2 }}
    >
      <YAxis dataKey="value" domain={["dataMin", "dataMax"]} hide />
      <Area
        dataKey="value"
        dot={false}
        fill="var(--color-value)"
        fillOpacity={0.14}
        isAnimationActive={false}
        stroke="var(--color-value)"
        strokeWidth={1.25}
        type="monotone"
      />
    </AreaChart>
  </ChartContainer>
);

const ChartSparkline = () => (
  <div className="grid w-full max-w-lg grid-cols-3 gap-4">
    <div className="flex flex-col gap-1">
      <span className="text-muted-foreground text-xs">Bitrate</span>
      <span className="text-sm font-semibold tabular-nums">6,012 kbps</span>
      <Sparkline
        config={neutral}
        values={[
          6010, 5980, 6040, 5990, 6020, 5210, 3870, 4960, 5940, 6010, 6030,
          6012,
        ]}
      />
    </div>
    <div className="flex flex-col gap-1">
      <span className="text-muted-foreground text-xs">Viewers</span>
      <span className="text-sm font-semibold tabular-nums">214</span>
      <Sparkline
        config={neutral}
        values={[42, 66, 81, 102, 120, 133, 151, 168, 177, 190, 205, 214]}
      />
    </div>
    <div className="flex flex-col gap-1">
      <span className="text-muted-foreground flex items-center gap-1 text-xs">
        <WarningIcon className="text-warning" />
        Dropped frames
      </span>
      <span className="text-sm font-semibold tabular-nums">2.4%</span>
      <Sparkline
        config={warning}
        values={[0, 0, 0.1, 0, 0.2, 1.1, 3.8, 2.9, 2.2, 2.6, 2.3, 2.4]}
      />
    </div>
  </div>
);

export default ChartSparkline;
```

### Bars

One neutral series with its value at the tip of each bar. The platform names on the axis carry identity, so the bars need no colour of their own.

```tsx title="components/examples/chart-bar.tsx"
"use client";

import { Bar, BarChart, LabelList, XAxis, YAxis } from "recharts";

import {
  ChartContainer,
  ChartTooltip,
  ChartTooltipContent,
} from "@/components/ui/chart";
import type { ChartConfig } from "@/components/ui/chart";

const VIEWERS = [
  { platform: "YouTube", viewers: 128 },
  { platform: "Twitch", viewers: 86 },
  { platform: "Kick", viewers: 12 },
];

// One neutral series: the platform names on the axis carry identity.
const config = {
  viewers: { color: "var(--muted-foreground)", label: "Viewers" },
} satisfies ChartConfig;

const ChartBar = () => (
  <ChartContainer className="aspect-auto h-36 w-full max-w-md" config={config}>
    <BarChart data={VIEWERS} layout="vertical" margin={{ left: 0, right: 32 }}>
      <XAxis dataKey="viewers" hide type="number" />
      <YAxis
        axisLine={false}
        dataKey="platform"
        tickLine={false}
        type="category"
        width={64}
      />
      <ChartTooltip
        content={<ChartTooltipContent hideLabel />}
        cursor={false}
      />
      <Bar
        barSize={20}
        dataKey="viewers"
        fill="var(--color-viewers)"
        radius={[0, 4, 4, 0]}
      >
        <LabelList
          className="fill-foreground"
          dataKey="viewers"
          offset={8}
          position="right"
        />
      </Bar>
    </BarChart>
  </ChartContainer>
);

export default ChartBar;
```

## Theming

The theme has no `--chart-*` palette. Videorc's chrome is monochrome and colour carries meaning, so a chart colours its series from the tokens it already has:

| Colour | When |
| --- | --- |
| `var(--foreground)`, `var(--muted-foreground)` | Every series, by default |
| `var(--warning)` | A reading that needs attention |
| `var(--destructive)` | A failure |
| `glass-float` | The tooltip: the popup glass with its rim and drop |
| `rounded-row` | The tooltip's 8 px radius |
| `stroke-border`, `fill-muted-foreground` | Grid lines, reference lines and axis text |

Give a series a `theme` instead of a `color` when it needs a different value in light and dark.

## Accessibility

Recharts' `accessibilityLayer` (on by default) lets the keyboard move through a chart's points and opens the tooltip on each. A chart is never the only place its numbers live: say the current reading in words beside it, and mark a decorative sparkline `aria-hidden`.

## API reference

### ChartContainer

Every `div` prop, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `config` | `ChartConfig` | — | Each series' label, icon and color (or theme: { light, dark }). |
| `initialDimension` | `{ width: number; height: number }` | `{ width: 320, height: 200 }` | The first frame's size, before the container is measured. |

### ChartTooltipContent

Every Recharts `Tooltip` content prop, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `indicator` | `"dot" \| "line" \| "dashed"` | `"dot"` | — |
| `hideLabel` | `boolean` | `false` | — |
| `hideIndicator` | `boolean` | `false` | — |
| `nameKey` | `string` | — | The payload key that names a series. |
| `labelKey` | `string` | — | The payload key for the tooltip's label. |

### ChartLegendContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `hideIcon` | `boolean` | `false` | — |
| `nameKey` | `string` | — | The payload key that names a series. |

`ChartTooltip` and `ChartLegend` are Recharts' `Tooltip` and `Legend`.

# Checkbox (/docs/components/checkbox)

```tsx title="components/examples/checkbox-demo.tsx"
"use client";

import { Checkbox } from "@/components/ui/checkbox";
import { Field, FieldLabel } from "@/components/ui/field";

const CheckboxDemo = () => (
  <Field orientation="horizontal">
    <Checkbox defaultChecked />
    <FieldLabel>Include markers in the export</FieldLabel>
  </Field>
);

export default CheckboxDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/checkbox
```

## Usage

```tsx
import { Checkbox } from "@/components/ui/checkbox";
```

```tsx
<Field orientation="horizontal">
  <Checkbox defaultChecked />
  <FieldLabel>Include markers in the export</FieldLabel>
</Field>
```

## Examples

### With a description

Put the label and a `FieldDescription` in a `FieldContent` beside the checkbox. The description describes the checkbox, and a disabled one says why.

```tsx title="components/examples/checkbox-description.tsx"
"use client";

import { Checkbox } from "@/components/ui/checkbox";
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldGroup,
  FieldLabel,
} from "@/components/ui/field";

const CheckboxDescription = () => (
  <FieldGroup className="max-w-sm">
    <Field orientation="horizontal">
      <Checkbox defaultChecked />
      <FieldContent>
        <FieldLabel>Keep original recording</FieldLabel>
        <FieldDescription>
          Clean cut saves a new file and leaves the original where it is.
        </FieldDescription>
      </FieldContent>
    </Field>
    <Field data-disabled="true" orientation="horizontal">
      <Checkbox disabled />
      <FieldContent>
        <FieldLabel>Upload to YouTube when it ends</FieldLabel>
        <FieldDescription>
          Connect YouTube in Livestream first.
        </FieldDescription>
      </FieldContent>
    </Field>
  </FieldGroup>
);

export default CheckboxDescription;
```

### Indeterminate

A header checkbox over some of its rows is `indeterminate`: it fills like checked and draws a dash. Clear it once every row, or none, is checked.

```tsx title="components/examples/checkbox-indeterminate.tsx"
"use client";

import { useState } from "react";

import { Checkbox } from "@/components/ui/checkbox";
import { Field, FieldGroup, FieldLabel } from "@/components/ui/field";

const RECORDINGS = [
  "Friday night speedruns",
  "Q&A with chat",
  "Studio test, take 3",
];

const CheckboxIndeterminate = () => {
  const [selected, setSelected] = useState(RECORDINGS.slice(0, 1));
  const all = selected.length === RECORDINGS.length;
  const some = selected.length > 0 && !all;
  return (
    <div className="flex max-w-xs flex-col gap-3">
      <Field orientation="horizontal">
        <Checkbox
          checked={all}
          indeterminate={some}
          onCheckedChange={() => setSelected(all ? [] : RECORDINGS)}
        />
        <FieldLabel>Select all recordings in view</FieldLabel>
      </Field>
      <div className="pl-6">
        <FieldGroup data-slot="checkbox-group">
          {RECORDINGS.map((recording) => (
            <Field key={recording} orientation="horizontal">
              <Checkbox
                checked={selected.includes(recording)}
                onCheckedChange={(checked) =>
                  setSelected((current) =>
                    checked
                      ? [...current, recording]
                      : current.filter((item) => item !== recording)
                  )
                }
              />
              <FieldLabel>{recording}</FieldLabel>
            </Field>
          ))}
        </FieldGroup>
      </div>
    </div>
  );
};

export default CheckboxIndeterminate;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `chrome-fill` | The fill and ink while checked or indeterminate |
| `bg-input/90` | The recessed box while unchecked |
| `rounded-chip` | The 6 px control radius |
| `data-checked`, `data-unchecked`, `data-indeterminate` | The state, from Base UI |
| `data-disabled` | Dims to 50% |
| `aria-invalid` | Draws the destructive border and ring |

## Keyboard

| Key              | Action                             |
| ---------------- | ---------------------------------- |
| <kbd>Space</kbd> | Toggles the checkbox               |
| <kbd>Enter</kbd> | Submits its form; it never toggles |
| <kbd>Tab</kbd>   | Moves focus to the next control    |

## Accessibility

The checkbox is a `role="checkbox"` span with `aria-checked` (`"mixed"` while indeterminate), beside a hidden native input that carries its form value. Its `id` goes on that hidden input, so a `FieldLabel` or a [Label](/docs/components/label) with `htmlFor` toggles it on click, and Base UI names the checkbox by that label. A row of checkboxes with no visible labels, such as a list's select column, names each one with `aria-label`.

## API reference

Every [Base UI Checkbox](https://base-ui.com/react/components/checkbox) root prop, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | — | The controlled state. |
| `defaultChecked` | `boolean` | `false` | The uncontrolled starting state. |
| `indeterminate` | `boolean` | `false` | Fills like checked and draws a dash, for a header over some of its rows. |
| `onCheckedChange` | `(checked: boolean, eventDetails) => void` | — | Called with the next state. |
| `id` | `string` | — | Lands on the hidden input. Inside a Field, one is made when it is missing, and the FieldLabel points at it. |

# Chrome Row (/docs/components/chrome-row)

```tsx title="components/examples/chrome-row-demo.tsx"
"use client";

import { Badge } from "@/components/ui/badge";
import { CHROME_ROW_CLASS } from "@/components/ui/chrome-row";
import { cn } from "@/lib/utils";

const ChromeRowDemo = () => (
  <ol
    aria-label="Chat messages"
    className="flex w-full max-w-sm flex-col gap-1"
  >
    <li className="rounded-row px-3 py-2 text-sm">
      <span className="text-muted-foreground font-medium">jonas</span> The new
      overlay looks great.
    </li>
    <li className={cn("rounded-row px-3 py-2 text-sm", CHROME_ROW_CLASS.live)}>
      <div className="mb-1 flex items-center gap-2">
        <span className="text-muted-foreground font-medium">nightowl</span>
        <Badge variant="chrome">On stream</Badge>
      </div>
      What camera is that?
    </li>
    <li
      className={cn("rounded-row px-3 py-2 text-sm", CHROME_ROW_CLASS.member)}
    >
      <div className="mb-1 flex items-center gap-2">
        <span className="text-muted-foreground font-medium">maya_streams</span>
        <Badge variant="plate">Member</Badge>
      </div>
      Hi from Lisbon!
    </li>
  </ol>
);

export default ChromeRowDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/chrome-row
```

## Usage

```tsx
import { CHROME_ROW_CLASS } from "@/components/ui/chrome-row";
```

```tsx
<li className={cn("rounded-row px-3 py-2", onStream && CHROME_ROW_CLASS.live)}>
  {message}
</li>
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `CHROME_ROW_CLASS.live` (`chrome-row-live`) | The row that's on stream: a chrome plate, a top line, a rim and a 2 px polished edge down the left |
| `CHROME_ROW_CLASS.member` (`chrome-row-member`) | A member's row: a plate at half strength with a 2 px edge in `--member`, so a paid message still reads louder |
| `--chrome-row-*` | The plates' stops, rim and hover lift, per theme |

Both plates sit on the theme's solid, so the text tiers keep their contrast whatever sits behind. Hover adds a faint lift. They're static: no transition, no motion and no `backdrop-filter`, so a long virtualized chat costs no more than a flat tint.

## Accessibility

A plate is colour only. Say what it means in words too: an On stream chip on the live row, a Member chip on a member's row.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `CHROME_ROW_CLASS.live` | `"chrome-row-live"` | — | The on-stream row. |
| `CHROME_ROW_CLASS.member` | `"chrome-row-member"` | — | A member's row. |

# Collapsible (/docs/components/collapsible)

```tsx title="components/examples/collapsible-demo.tsx"
"use client";

import { ChevronDownIcon } from "@/components/icons";
import { Button } from "@/components/ui/button";
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from "@/components/ui/collapsible";

const ENCODER_SETTINGS = [
  { label: "Keyframe interval", value: "2 s" },
  { label: "B-frames", value: "2" },
  { label: "Encoder preset", value: "Quality" },
];

const CollapsibleDemo = () => (
  <Collapsible className="w-full max-w-xs">
    <CollapsibleTrigger render={<Button variant="ghost" />}>
      Advanced settings
      <ChevronDownIcon
        className="transition-transform duration-150 ease-out group-data-panel-open/button:rotate-180"
        data-icon="inline-end"
      />
    </CollapsibleTrigger>
    <CollapsibleContent>
      <dl className="mt-2 flex flex-col gap-1 px-3 text-sm">
        {ENCODER_SETTINGS.map((setting) => (
          <div className="flex justify-between gap-4" key={setting.label}>
            <dt className="text-muted-foreground">{setting.label}</dt>
            <dd>{setting.value}</dd>
          </div>
        ))}
      </dl>
    </CollapsibleContent>
  </Collapsible>
);

export default CollapsibleDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/collapsible
```

## Usage

```tsx
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from "@/components/ui/collapsible";
```

```tsx
<Collapsible>
  <CollapsibleTrigger>Advanced settings</CollapsibleTrigger>
  <CollapsibleContent>{settings}</CollapsibleContent>
</Collapsible>
```

## Anatomy

```tsx
<Collapsible>
  <CollapsibleTrigger />
  <CollapsibleContent />
</Collapsible>
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `data-panel-open` | On the trigger while open: turn a chevron with `group-data-panel-open:rotate-180` |
| `data-open`, `data-closed` | On the root and the panel |
| `--collapsible-panel-height` | The panel's measured height, to animate it |

## Keyboard

| Key                               | Action                    |
| --------------------------------- | ------------------------- |
| <kbd>Enter</kbd> <kbd>Space</kbd> | Opens or closes the panel |

## Accessibility

The trigger is a button with `aria-expanded` and `aria-controls`. Render your own button with `render={<Button variant="ghost" />}` to keep the desktop sizes; wrap the trigger in a heading when the section is one.

## API reference

Every [Base UI Collapsible](https://base-ui.com/react/components/collapsible) prop: `open`, `defaultOpen` and `onOpenChange` on `Collapsible`, `render` on `CollapsibleTrigger`, and `keepMounted` or `hiddenUntilFound` on `CollapsibleContent` (the Base UI Panel).

# Command (/docs/components/command)

```tsx title="components/examples/command-demo.tsx"
"use client";

import {
  LibraryIcon,
  LivestreamIcon,
  MicrophoneIcon,
  RecordIcon,
  SourcesIcon,
  StudioIcon,
} from "@/components/icons";
import {
  Command,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandSeparator,
  CommandShortcut,
} from "@/components/ui/command";
import { ShortcutKeys } from "@/components/ui/shortcut-keys";

const CommandDemo = () => (
  // Inline, Command needs a surface: it paints none of its own.
  <div className="glass-float-dialog rounded-panel w-full max-w-lg overflow-hidden border">
    <Command>
      <CommandInput placeholder="Search commands…" />
      <CommandList>
        <CommandEmpty>No results found.</CommandEmpty>
        <CommandGroup heading="Session">
          <CommandItem keywords={["record"]}>
            <RecordIcon />
            Start recording
            <CommandShortcut>
              <ShortcutKeys accelerator="CmdOrCtrl+Shift+R" />
            </CommandShortcut>
          </CommandItem>
          <CommandItem keywords={["stream", "livestream", "broadcast"]}>
            <LivestreamIcon />
            Go Live…
          </CommandItem>
          <CommandItem keywords={["mic", "audio", "mute"]}>
            <MicrophoneIcon />
            Mute microphone
          </CommandItem>
        </CommandGroup>
        <CommandSeparator />
        <CommandGroup heading="Pages">
          <CommandItem>
            <StudioIcon />
            Studio
            <CommandShortcut>
              <ShortcutKeys accelerator="CmdOrCtrl+1" />
            </CommandShortcut>
          </CommandItem>
          <CommandItem>
            <SourcesIcon />
            Sources
            <CommandShortcut>
              <ShortcutKeys accelerator="CmdOrCtrl+2" />
            </CommandShortcut>
          </CommandItem>
          <CommandItem>
            <LibraryIcon />
            Library
            <CommandShortcut>
              <ShortcutKeys accelerator="CmdOrCtrl+8" />
            </CommandShortcut>
          </CommandItem>
        </CommandGroup>
      </CommandList>
    </Command>
  </div>
);

export default CommandDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/command
```

## Usage

```tsx
import {
  CommandDialog,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
} from "@/components/ui/command";
```

```tsx
<CommandDialog onOpenChange={setOpen} open={open}>
  <CommandInput placeholder="Search commands…" />
  <CommandList>
    <CommandEmpty>No results found.</CommandEmpty>
    <CommandGroup heading="Session">
      <CommandItem keywords={["record"]} onSelect={startRecording}>
        <RecordIcon />
        Start recording
      </CommandItem>
    </CommandGroup>
  </CommandList>
</CommandDialog>
```

`CommandDialog` wraps its children in `Command` itself: every cmdk part reads the store `Command` provides, and one rendered outside it crashes on its first render. `Command` paints no surface of its own. In a dialog or a popover it stays transparent, and inline it needs a surface around it.

## Anatomy

```tsx
<CommandDialog>
  <CommandInput />
  <CommandList>
    <CommandEmpty />
    <CommandGroup>
      <CommandItem>
        <CommandShortcut />
      </CommandItem>
    </CommandGroup>
    <CommandSeparator />
  </CommandList>
  <CommandFooter />
</CommandDialog>
```

## Examples

### Palette

The ⌘K palette: a `lg` dialog in the upper part of the window. `value` and `onValueChange` are the selected item, so the `CommandFooter` can name the action `Enter` runs.

```tsx title="components/examples/command-dialog.tsx"
"use client";

import { useEffect, useState } from "react";

import {
  OutputIcon,
  SceneIcon,
  SearchIcon,
  SettingsIcon,
  StudioIcon,
} from "@/components/icons";
import { Button } from "@/components/ui/button";
import {
  CommandDialog,
  CommandEmpty,
  CommandFooter,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
} from "@/components/ui/command";
import { ShortcutKeys } from "@/components/ui/shortcut-keys";

const PAGES = [
  { icon: StudioIcon, label: "Studio" },
  { icon: SceneIcon, label: "Scene" },
  { icon: OutputIcon, label: "Output" },
  { icon: SettingsIcon, label: "Settings" },
] as const;

const CommandDialogExample = () => {
  const [open, setOpen] = useState(false);
  const [selected, setSelected] = useState("Open Studio");

  useEffect(() => {
    const onKeyDown = (event: KeyboardEvent) => {
      if (event.key === "k" && (event.metaKey || event.ctrlKey)) {
        event.preventDefault();
        setOpen((value) => !value);
      }
    };
    document.addEventListener("keydown", onKeyDown);
    return () => document.removeEventListener("keydown", onKeyDown);
  }, []);

  return (
    <>
      <Button onClick={() => setOpen(true)} variant="secondary">
        <SearchIcon data-icon="inline-start" />
        Search
        <ShortcutKeys accelerator="CmdOrCtrl+K" />
      </Button>
      <CommandDialog
        onOpenChange={setOpen}
        onValueChange={setSelected}
        open={open}
        value={selected}
      >
        <CommandInput placeholder="Search commands…" />
        <CommandList>
          <CommandEmpty>No results found.</CommandEmpty>
          <CommandGroup heading="Pages">
            {PAGES.map(({ icon: Icon, label }) => (
              <CommandItem
                key={label}
                onSelect={() => setOpen(false)}
                value={`Open ${label}`}
              >
                <Icon />
                {label}
              </CommandItem>
            ))}
          </CommandGroup>
        </CommandList>
        <CommandFooter>
          <span>{selected}</span>
          <ShortcutKeys accelerator="Enter" />
        </CommandFooter>
      </CommandDialog>
    </>
  );
};

export default CommandDialogExample;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `rounded-panel` | 12 px corners, matching the dialog tier around it |
| `text-lg`, `size-6` | The 18 px search field and its 24 px icon, over a hairline |
| `min-h-10`, `rounded-row` | 40 px rows with 8 px corners |
| `data-selected="true"` | The selected row: the `bg-accent` block, shown instantly |
| `text-subtle` | Group headings |
| `data-checked="true"` | On an item, shows its check |

## Keyboard

| Key                    | Action                          |
| ---------------------- | ------------------------------- |
| Typing                 | Filters the list                |
| `ArrowDown`, `ArrowUp` | Moves the selection             |
| `Home`, `End`          | Moves to the first or last item |
| `Enter`                | Runs the selected item          |
| `Escape`               | Closes the dialog               |

## Accessibility

The input is a combobox and the list a listbox; the selection is announced as it moves. `CommandDialog` carries a visually hidden title ("Search") and description. Give `CommandInput` an `aria-label` when its placeholder is the only label in view.

## API reference

Every [cmdk](https://github.com/pacocoursey/cmdk) prop, plus:

### CommandDialog

Every [Base UI Dialog](https://base-ui.com/react/components/dialog) root prop, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | `"Search"` | The visually hidden title. |
| `description` | `string` | `"Search for a command to run…"` | The visually hidden description. |
| `showCloseButton` | `boolean` | `false` | — |
| `value` | `string` | — | The selected item's value. |
| `onValueChange` | `(value: string) => void` | — | — |

# Context Menu (/docs/components/context-menu)

```tsx title="components/examples/context-menu-demo.tsx"
"use client";

import { CopyIcon, DeleteIcon, EditIcon } from "@/components/icons";
import {
  ContextMenu,
  ContextMenuContent,
  ContextMenuGroup,
  ContextMenuItem,
  ContextMenuSeparator,
  ContextMenuShortcut,
  ContextMenuTrigger,
} from "@/components/ui/context-menu";
import { ShortcutKeys } from "@/components/ui/shortcut-keys";

const ContextMenuDemo = () => (
  <ContextMenu>
    <ContextMenuTrigger>
      <div className="rounded-row text-muted-foreground flex h-32 w-72 items-center justify-center border text-sm">
        Right-click the scene
      </div>
    </ContextMenuTrigger>
    <ContextMenuContent className="w-52">
      <ContextMenuGroup>
        <ContextMenuItem>
          <EditIcon />
          Rename…
          <ContextMenuShortcut>
            <ShortcutKeys accelerator="Enter" />
          </ContextMenuShortcut>
        </ContextMenuItem>
        <ContextMenuItem>
          <CopyIcon />
          Duplicate
          <ContextMenuShortcut>
            <ShortcutKeys accelerator="CmdOrCtrl+D" />
          </ContextMenuShortcut>
        </ContextMenuItem>
      </ContextMenuGroup>
      <ContextMenuSeparator />
      <ContextMenuItem variant="destructive">
        <DeleteIcon />
        Delete scene…
      </ContextMenuItem>
    </ContextMenuContent>
  </ContextMenu>
);

export default ContextMenuDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/context-menu
```

## Usage

```tsx
import {
  ContextMenu,
  ContextMenuContent,
  ContextMenuItem,
  ContextMenuTrigger,
} from "@/components/ui/context-menu";
```

```tsx
<ContextMenu>
  <ContextMenuTrigger>{sceneCard}</ContextMenuTrigger>
  <ContextMenuContent>
    <ContextMenuItem onClick={rename}>Rename…</ContextMenuItem>
  </ContextMenuContent>
</ContextMenu>
```

A right-click is a shortcut, never the only way in: every action in a context menu is also in the item's [Dropdown Menu](/docs/components/dropdown-menu) or on screen.

## Anatomy

```tsx
<ContextMenu>
  <ContextMenuTrigger />
  <ContextMenuContent>
    <ContextMenuLabel />
    <ContextMenuGroup>
      <ContextMenuItem>
        <ContextMenuShortcut />
      </ContextMenuItem>
    </ContextMenuGroup>
    <ContextMenuSeparator />
    <ContextMenuCheckboxItem />
    <ContextMenuRadioGroup>
      <ContextMenuRadioItem />
    </ContextMenuRadioGroup>
    <ContextMenuSub>
      <ContextMenuSubTrigger />
      <ContextMenuSubContent />
    </ContextMenuSub>
  </ContextMenuContent>
</ContextMenu>
```

## Examples

### Checkbox items

The Stream Manager's stats bar: right-click it to choose which stats show. Checkbox items keep the menu open.

```tsx title="components/examples/context-menu-checkboxes.tsx"
"use client";

import { useState } from "react";

import {
  ContextMenu,
  ContextMenuCheckboxItem,
  ContextMenuContent,
  ContextMenuGroup,
  ContextMenuItem,
  ContextMenuLabel,
  ContextMenuSeparator,
  ContextMenuTrigger,
} from "@/components/ui/context-menu";

const STATS = [
  { id: "viewers", label: "Viewers" },
  { id: "bitrate", label: "Bitrate" },
  { id: "dropped", label: "Dropped frames" },
  { id: "uptime", label: "Uptime" },
] as const;

type StatId = (typeof STATS)[number]["id"];

const DEFAULT_STATS: StatId[] = ["viewers", "bitrate", "uptime"];

const ContextMenuCheckboxes = () => {
  const [shown, setShown] = useState<StatId[]>(DEFAULT_STATS);
  const toggle = (id: StatId, checked: boolean) =>
    setShown((current) =>
      checked ? [...current, id] : current.filter((entry) => entry !== id)
    );
  return (
    <ContextMenu>
      <ContextMenuTrigger className="w-full max-w-md">
        <div className="h-status-bar rounded-row text-meta text-muted-foreground flex items-center gap-4 border px-3">
          {STATS.filter((stat) => shown.includes(stat.id)).map((stat) => (
            <span key={stat.id}>{stat.label}</span>
          ))}
        </div>
      </ContextMenuTrigger>
      <ContextMenuContent className="w-52">
        <ContextMenuGroup>
          <ContextMenuLabel>Stats</ContextMenuLabel>
          {STATS.map((stat) => (
            <ContextMenuCheckboxItem
              checked={shown.includes(stat.id)}
              key={stat.id}
              onCheckedChange={(checked) => toggle(stat.id, checked)}
            >
              {stat.label}
            </ContextMenuCheckboxItem>
          ))}
        </ContextMenuGroup>
        <ContextMenuSeparator />
        <ContextMenuItem onClick={() => setShown(DEFAULT_STATS)}>
          Reset stats
        </ContextMenuItem>
      </ContextMenuContent>
    </ContextMenu>
  );
};

export default ContextMenuCheckboxes;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `glass-float` | The popup tier: the window's solid tone, a 1 px rim and the float drop |
| `rounded-lg` | The popup tier's 10 px corners, with a 4 px inset |
| `min-h-7`, `rounded-chip` | 28 px items with 6 px corners |
| `bg-accent` | The highlighted item |
| `data-variant="destructive"` | The destructive item's tone |
| `select-none` | On the trigger, so a right-click doesn't select its text |

## Keyboard

| Key                       | Action                       |
| ------------------------- | ---------------------------- |
| `ArrowDown`, `ArrowUp`    | Moves between items          |
| `ArrowRight`, `ArrowLeft` | Opens or closes a submenu    |
| `Enter`, `Space`          | Chooses the highlighted item |
| `Escape`                  | Closes the menu              |

## Accessibility

The menu opens from the pointer, so it has no keyboard path of its own; that is why its actions live somewhere else too. Like Dropdown Menu, it stops wheel events at its edge, and a `ContextMenuLabel` outside any group is a plain heading row.

## API reference

Every [Base UI Context Menu](https://base-ui.com/react/components/context-menu) prop, plus:

### ContextMenuContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"right"` | — |
| `sideOffset` | `number` | `0` | — |
| `align` | `"start" \| "center" \| "end"` | `"start"` | — |
| `alignOffset` | `number` | `4` | — |

### ContextMenuItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "destructive"` | `"default"` | — |

# Dialog (/docs/components/dialog)

```tsx title="components/examples/dialog-demo.tsx"
"use client";

import { Button } from "@/components/ui/button";
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";
import { Field, FieldLabel } from "@/components/ui/field";
import { Input } from "@/components/ui/input";

const DialogDemo = () => (
  <Dialog>
    <DialogTrigger render={<Button variant="secondary" />}>
      Rename scene…
    </DialogTrigger>
    <DialogContent size="sm">
      <DialogHeader>
        <DialogTitle>Rename scene</DialogTitle>
        <DialogDescription>
          The new name shows in the Studio and in Scene.
        </DialogDescription>
      </DialogHeader>
      <Field>
        <FieldLabel>Name</FieldLabel>
        <Input defaultValue="Just chatting" />
      </Field>
      <DialogFooter>
        <DialogClose render={<Button variant="ghost" />}>Cancel</DialogClose>
        <DialogClose render={<Button />}>Save</DialogClose>
      </DialogFooter>
    </DialogContent>
  </Dialog>
);

export default DialogDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/dialog
```

## Usage

```tsx
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";
```

```tsx
<Dialog>
  <DialogTrigger render={<Button variant="secondary" />}>
    Rename scene…
  </DialogTrigger>
  <DialogContent size="sm">
    <DialogHeader>
      <DialogTitle>Rename scene</DialogTitle>
      <DialogDescription>The new name shows in the Studio.</DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <DialogClose render={<Button variant="ghost" />}>Cancel</DialogClose>
      <Button onClick={save}>Save</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>
```

Size a dialog with `size`, never a `max-w-*` or `max-h-*` of its own.

## Anatomy

```tsx
<Dialog>
  <DialogTrigger />
  <DialogContent>
    <DialogHeader>
      <DialogTitle />
      <DialogDescription />
    </DialogHeader>
    <DialogBody />
    <DialogFooter>
      <DialogClose />
    </DialogFooter>
  </DialogContent>
</Dialog>
```

## Examples

### Sizes

`sm` (384 px) for a rename or one question, `md` (448 px, the default) for confirmations and short forms, `lg` (576 px) for forms, pickers and setup, `xl` (768 px) for review and media.

```tsx title="components/examples/dialog-sizes.tsx"
"use client";

import { Button } from "@/components/ui/button";
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";
import type { DialogSize } from "@/components/ui/dialog";

const SIZES: { size: DialogSize; title: string; use: string }[] = [
  { size: "sm", title: "Rename scene", use: "384 px: a rename, one question." },
  {
    size: "md",
    title: "Delete saved scene?",
    use: "448 px, the default: confirmations and short forms.",
  },
  {
    size: "lg",
    title: "Set up your microphone",
    use: "576 px: forms, pickers and setup.",
  },
  {
    size: "xl",
    title: "Go Live",
    use: "768 px: review and media, such as Go Live and markers.",
  },
];

const DialogSizes = () => (
  <div className="flex flex-wrap items-center gap-2">
    {SIZES.map(({ size, title, use }) => (
      <Dialog key={size}>
        <DialogTrigger render={<Button variant="secondary" />}>
          {size}
        </DialogTrigger>
        <DialogContent size={size}>
          <DialogHeader>
            <DialogTitle>{title}</DialogTitle>
            <DialogDescription>{use}</DialogDescription>
          </DialogHeader>
          <DialogFooter showCloseButton />
        </DialogContent>
      </Dialog>
    ))}
  </div>
);

export default DialogSizes;
```

### Scrolling body

A dialog is never taller than the window less 16 px a side. Put long content in a `DialogBody`: it takes the height the header and footer leave and scrolls, so they stay in view. A dialog without one scrolls whole.

```tsx title="components/examples/dialog-body.tsx"
"use client";

import { MarkerIcon } from "@/components/icons";
import { Button } from "@/components/ui/button";
import {
  Dialog,
  DialogBody,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";

const MARKERS = Array.from({ length: 24 }, (_, index) => ({
  id: `marker-${index + 1}`,
  label: `Marker ${index + 1}`,
  time: `0:${String(index * 2 + 3).padStart(2, "0")}:12`,
}));

const DialogBodyExample = () => (
  <Dialog>
    <DialogTrigger render={<Button variant="secondary" />}>
      <MarkerIcon data-icon="inline-start" />
      Review markers…
    </DialogTrigger>
    <DialogContent size="lg">
      <DialogHeader>
        <DialogTitle>Markers</DialogTitle>
        <DialogDescription>
          24 markers in this recording. Jump to one to review it.
        </DialogDescription>
      </DialogHeader>
      <DialogBody>
        <ul className="divide-border divide-y">
          {MARKERS.map((marker) => (
            <li
              className="h-row flex items-center justify-between text-sm"
              key={marker.id}
            >
              {marker.label}
              <span className="text-meta text-muted-foreground tabular-nums">
                {marker.time}
              </span>
            </li>
          ))}
        </ul>
      </DialogBody>
      <DialogFooter>
        <DialogClose render={<Button />}>Done</DialogClose>
      </DialogFooter>
    </DialogContent>
  </Dialog>
);

export default DialogBodyExample;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `glass-float-dialog` | The dialog tier: a step brighter than the popup tier, with its own drop |
| `rounded-panel`, `p-5`, `gap-5` | 12 px corners and the dialog's spacing |
| `max-h-[calc(100vh-2rem)]` | The height rule |
| `data-size` | `sm`, `md`, `lg` or `xl` |
| `bg-black/30` | The overlay, with no backdrop blur: blur wedged the compositor on a vibrancy window |
| `data-open`, `data-closed` | Fades and scales from 0.98 in 100 ms |

`dialogContentVariants({ size })` returns the dialog's classes, `DIALOG_SURFACE_CLASS` the surface alone (for a card on the dialog tier that isn't a dialog), and `DIALOG_SIZE_CLASS` the widths.

## Keyboard

| Key                | Action                                                  |
| ------------------ | ------------------------------------------------------- |
| `Tab`, `Shift+Tab` | Moves through the dialog's controls; focus stays inside |
| `Escape`           | Closes the dialog                                       |

## Accessibility

`DialogTitle` names the dialog and `DialogDescription` describes it. Focus moves to the first control on open (choose another with `initialFocus`) and back to the trigger on close. The close button reads "Close".

## API reference

Every [Base UI Dialog](https://base-ui.com/react/components/dialog) prop, plus:

### DialogContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | — |
| `showCloseButton` | `boolean` | `true` | The ghost close button, top right. |

### DialogFooter

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `showCloseButton` | `boolean` | `false` | Adds an outline Close button. |

# Disabled Reason (/docs/components/disabled-reason)

```tsx title="components/examples/disabled-reason-demo.tsx"
"use client";

import { Button } from "@/components/ui/button";
import { DisabledReason } from "@/components/ui/disabled-reason";

const DisabledReasonDemo = () => (
  <div className="flex items-center gap-2">
    <DisabledReason reason="Add a destination before you go live.">
      <Button disabled>Go Live…</Button>
    </DisabledReason>
    <DisabledReason reason="Stop the recording before you delete it.">
      <Button disabled variant="destructive">
        Delete
      </Button>
    </DisabledReason>
  </div>
);

export default DisabledReasonDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/disabled-reason
```

## Usage

```tsx
import { DisabledReason } from "@/components/ui/disabled-reason";
```

```tsx
<DisabledReason
  reason={canGoLive ? null : "Add a destination before you go live."}
>
  <Button disabled={!canGoLive}>Go Live…</Button>
</DisabledReason>
```

Pass the reason only while the control is disabled. With no reason the control renders exactly as it is, with no extra tab stop.

## Examples

### In a menu

A menu or select item is reachable while disabled: Base UI keeps it in the arrow-key order as `aria-disabled`, and the highlight lands on it. Pass `focusable={false}` and the item itself takes the hover and the focus and is described, with no wrapper and no second stop in the list.

```tsx title="components/examples/disabled-reason-menu.tsx"
"use client";

import { MoreIcon } from "@/components/icons";
import { Button } from "@/components/ui/button";
import { DisabledReason } from "@/components/ui/disabled-reason";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu";

const DisabledReasonMenu = () => (
  <DropdownMenu>
    <DropdownMenuTrigger
      render={
        <Button
          aria-label="Actions for Launch demo"
          size="icon"
          variant="ghost"
        />
      }
    >
      <MoreIcon weight="bold" />
    </DropdownMenuTrigger>
    <DropdownMenuContent>
      <DropdownMenuItem>Rename…</DropdownMenuItem>
      <DropdownMenuItem>Show in Finder</DropdownMenuItem>
      <DisabledReason
        focusable={false}
        reason="Wait for the upload to finish."
        side="left"
      >
        <DropdownMenuItem disabled>Delete</DropdownMenuItem>
      </DisabledReason>
    </DropdownMenuContent>
  </DropdownMenu>
);

export default DisabledReasonMenu;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `rounded-chip`, `focus-visible:ring-3` | The wrapper's focus ring, around the control |
| `data-disabled:pointer-events-auto` | Added to a menu or select item with `focusable={false}`, so it takes the hover |
| `data-slot="disabled-reason"` | The focusable wrapper |
| `data-slot="disabled-reason-text"` | The hidden description |

## Keyboard

| Key | Action |
| --- | --- |
| <kbd>Tab</kbd> | Focuses the wrapper of a disabled control and shows the reason |
| <kbd>↑</kbd> <kbd>↓</kbd> | In a menu, highlight a disabled item and show its reason |
| <kbd>Esc</kbd> | Hides the reason |

## Accessibility

A disabled control takes no pointer events and no focus, so a `title` on it never shows. The wrapper is a tab stop with the reason as its `aria-describedby`, kept in the DOM, hidden, not only while the tooltip shows. Use `label` when the control's own name isn't enough to say what the wrapper stands for. Never pass `focusable={false}` for a native disabled `<button>`: it gets no pointer events and no focus, so only the wrapper works.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `reason` | `ReactNode` | — | The one reason in a sentence; null or empty while the control works. |
| `children` | `ReactElement` | — | The disabled control. |
| `id` | `string` | — | The description's id, when a caller needs a stable one. |
| `label` | `string` | — | The wrapper's accessible name. |
| `focusable` | `boolean` | `true` | False for a menu or select item, which takes the highlight itself. |
| `tabIndex` | `number` | `0` | The wrapper's tab stop. |
| `className` | `string` | — | Layout for the wrapper (flex-1, w-full), never styling. |
| `side` | `"top" \| "bottom" \| "left" \| "right"` | `"top"` | — |
| `align` | `"start" \| "center" \| "end"` | `"center"` | — |

# Dropdown Menu (/docs/components/dropdown-menu)

```tsx title="components/examples/dropdown-menu-demo.tsx"
"use client";

import {
  CopyIcon,
  DeleteIcon,
  EditIcon,
  FolderIcon,
  MoreIcon,
} from "@/components/icons";
import { Button } from "@/components/ui/button";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu";
import { ShortcutKeys } from "@/components/ui/shortcut-keys";

const DropdownMenuDemo = () => (
  <DropdownMenu>
    <DropdownMenuTrigger
      render={<Button aria-label="More actions" size="icon" variant="ghost" />}
    >
      <MoreIcon weight="bold" />
    </DropdownMenuTrigger>
    <DropdownMenuContent align="end" className="w-52">
      <DropdownMenuGroup>
        <DropdownMenuItem>
          <EditIcon />
          Rename…
          <DropdownMenuShortcut>
            <ShortcutKeys accelerator="Enter" />
          </DropdownMenuShortcut>
        </DropdownMenuItem>
        <DropdownMenuItem>
          <CopyIcon />
          Duplicate
          <DropdownMenuShortcut>
            <ShortcutKeys accelerator="CmdOrCtrl+D" />
          </DropdownMenuShortcut>
        </DropdownMenuItem>
        <DropdownMenuItem>
          <FolderIcon />
          Show in Finder
        </DropdownMenuItem>
      </DropdownMenuGroup>
      <DropdownMenuSeparator />
      <DropdownMenuItem variant="destructive">
        <DeleteIcon />
        Delete recording…
      </DropdownMenuItem>
    </DropdownMenuContent>
  </DropdownMenu>
);

export default DropdownMenuDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/dropdown-menu
```

## Usage

```tsx
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu";
```

```tsx
<DropdownMenu>
  <DropdownMenuTrigger
    render={<Button aria-label="More actions" size="icon" variant="ghost" />}
  >
    <MoreIcon weight="bold" />
  </DropdownMenuTrigger>
  <DropdownMenuContent align="end">
    <DropdownMenuItem onClick={rename}>Rename…</DropdownMenuItem>
    <DropdownMenuItem onClick={confirmDelete} variant="destructive">
      Delete recording…
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

Group items with a hairline between groups, and put destructive items last. An item runs its action from `onClick` and closes the menu; checkbox and radio items keep it open.

## Anatomy

```tsx
<DropdownMenu>
  <DropdownMenuTrigger />
  <DropdownMenuContent>
    <DropdownMenuLabel />
    <DropdownMenuGroup>
      <DropdownMenuLabel />
      <DropdownMenuItem>
        <DropdownMenuShortcut />
      </DropdownMenuItem>
    </DropdownMenuGroup>
    <DropdownMenuSeparator />
    <DropdownMenuCheckboxItem />
    <DropdownMenuRadioGroup>
      <DropdownMenuRadioItem />
    </DropdownMenuRadioGroup>
    <DropdownMenuSub>
      <DropdownMenuSubTrigger />
      <DropdownMenuSubContent />
    </DropdownMenuSub>
  </DropdownMenuContent>
</DropdownMenu>
```

## Examples

### Checkbox items

Several filters on at once, such as which Activity events show. The menu stays open while you toggle.

```tsx title="components/examples/dropdown-menu-checkboxes.tsx"
"use client";

import { useState } from "react";

import { AdjustIcon } from "@/components/icons";
import { Button } from "@/components/ui/button";
import {
  DropdownMenu,
  DropdownMenuCheckboxItem,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuLabel,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu";

const EVENTS = [
  { id: "follows", label: "Follows" },
  { id: "subscriptions", label: "Subscriptions" },
  { id: "tips", label: "Tips and cheers" },
  { id: "raids", label: "Raids" },
] as const;

type EventId = (typeof EVENTS)[number]["id"];

const DropdownMenuCheckboxes = () => {
  const [shown, setShown] = useState<EventId[]>(["follows", "tips", "raids"]);
  const toggle = (id: EventId, checked: boolean) =>
    setShown((current) =>
      checked ? [...current, id] : current.filter((entry) => entry !== id)
    );
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="secondary" />}>
        <AdjustIcon data-icon="inline-start" />
        Filter activity
      </DropdownMenuTrigger>
      <DropdownMenuContent className="w-52">
        <DropdownMenuGroup>
          <DropdownMenuLabel>Show</DropdownMenuLabel>
          {EVENTS.map((event) => (
            <DropdownMenuCheckboxItem
              checked={shown.includes(event.id)}
              key={event.id}
              onCheckedChange={(checked) => toggle(event.id, checked)}
            >
              {event.label}
            </DropdownMenuCheckboxItem>
          ))}
        </DropdownMenuGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  );
};

export default DropdownMenuCheckboxes;
```

### Radio group

One choice from a few, such as where a chat message goes. A `DropdownMenuLabel` outside any group is a plain heading row; inside a group it names the group.

```tsx title="components/examples/dropdown-menu-radio-group.tsx"
"use client";

import { useState } from "react";

import { SendIcon } from "@/components/icons";
import { Button } from "@/components/ui/button";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuLabel,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu";

const DESTINATIONS = [
  { label: "All destinations", value: "all" },
  { label: "YouTube", value: "youtube" },
  { label: "Twitch", value: "twitch" },
] as const;

const DropdownMenuRadioGroupExample = () => {
  const [destination, setDestination] = useState<string>("all");
  const label = DESTINATIONS.find(
    (entry) => entry.value === destination
  )?.label;
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="secondary" />}>
        <SendIcon data-icon="inline-start" />
        {label}
      </DropdownMenuTrigger>
      <DropdownMenuContent className="w-52">
        <DropdownMenuLabel>Send to</DropdownMenuLabel>
        <DropdownMenuRadioGroup
          onValueChange={(value: string) => setDestination(value)}
          value={destination}
        >
          {DESTINATIONS.map((entry) => (
            <DropdownMenuRadioItem key={entry.value} value={entry.value}>
              {entry.label}
            </DropdownMenuRadioItem>
          ))}
        </DropdownMenuRadioGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  );
};

export default DropdownMenuRadioGroupExample;
```

### Submenu

A list that would crowd the menu, such as the scenes a source can join.

```tsx title="components/examples/dropdown-menu-submenu.tsx"
"use client";

import { MoreIcon, SceneIcon } from "@/components/icons";
import { Button } from "@/components/ui/button";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuSub,
  DropdownMenuSubContent,
  DropdownMenuSubTrigger,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu";

const SCENES = ["Just chatting", "Screen and camera", "Be right back"];

const DropdownMenuSubmenu = () => (
  <DropdownMenu>
    <DropdownMenuTrigger
      render={
        <Button aria-label="More source actions" size="icon" variant="ghost" />
      }
    >
      <MoreIcon weight="bold" />
    </DropdownMenuTrigger>
    <DropdownMenuContent className="w-52">
      <DropdownMenuItem>Rename…</DropdownMenuItem>
      <DropdownMenuSub>
        <DropdownMenuSubTrigger>
          <SceneIcon />
          Add to scene
        </DropdownMenuSubTrigger>
        <DropdownMenuSubContent>
          <DropdownMenuGroup>
            {SCENES.map((scene) => (
              <DropdownMenuItem key={scene}>{scene}</DropdownMenuItem>
            ))}
          </DropdownMenuGroup>
        </DropdownMenuSubContent>
      </DropdownMenuSub>
      <DropdownMenuItem>Show in all scenes</DropdownMenuItem>
    </DropdownMenuContent>
  </DropdownMenu>
);

export default DropdownMenuSubmenu;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `glass-float` | The popup tier: the window's solid tone, a 1 px rim and the float drop |
| `rounded-lg` | The popup tier's 10 px corners, with a 4 px inset |
| `min-h-7`, `rounded-chip` | 28 px items with 6 px corners, concentric inside the inset |
| `bg-accent` | The highlighted item |
| `data-variant="destructive"` | The destructive item's tone |
| `data-popup-open` | On the trigger and sub trigger while their menu is open |
| `overscroll-contain` | A long menu's scroll doesn't chain to the page |

## Keyboard

| Key | Action |
| --- | --- |
| `Enter`, `Space`, `ArrowDown` | On the trigger, opens the menu |
| `ArrowDown`, `ArrowUp` | Moves between items |
| `ArrowRight`, `ArrowLeft` | Opens or closes a submenu |
| `Enter`, `Space` | Chooses the highlighted item |
| A letter | Moves to the next item that starts with it |
| `Escape` | Closes the menu and returns focus to the trigger |

## Accessibility

An icon-only trigger needs an `aria-label`. A disabled item takes no hover, so a reason goes in text under it, not in a tooltip. The menu stops wheel events at its edge: it's portalled, but React still bubbles events through the trigger's ancestors, and a fader or a scrolling pane behind it shouldn't move.

## API reference

Every [Base UI Menu](https://base-ui.com/react/components/menu) prop, plus:

### DropdownMenuContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | — |
| `sideOffset` | `number` | `4` | — |
| `align` | `"start" \| "center" \| "end"` | `"start"` | — |
| `alignOffset` | `number` | `0` | — |

### DropdownMenuItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "destructive"` | `"default"` | — |
| `closeOnClick` | `boolean` | `true` | Checkbox and radio items default to false. |

### DropdownMenuSubContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"right"` | — |
| `sideOffset` | `number` | `0` | — |
| `align` | `"start" \| "center" \| "end"` | `"start"` | — |
| `alignOffset` | `number` | `-3` | Lines its first item up with the sub trigger. |

# Empty (/docs/components/empty)

```tsx title="components/examples/empty-demo.tsx"
"use client";

import { Button } from "@/components/ui/button";
import {
  Empty,
  EmptyContent,
  EmptyDescription,
  EmptyHeader,
  EmptyTitle,
} from "@/components/ui/empty";

const EmptyDemo = () => (
  <Empty>
    <EmptyHeader>
      <EmptyTitle>No recordings yet</EmptyTitle>
      <EmptyDescription>
        Recordings you make in the Studio show up here.
      </EmptyDescription>
    </EmptyHeader>
    <EmptyContent>
      <Button variant="secondary">Open Studio</Button>
    </EmptyContent>
  </Empty>
);

export default EmptyDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/empty
```

## Usage

```tsx
import {
  Empty,
  EmptyDescription,
  EmptyHeader,
  EmptyTitle,
} from "@/components/ui/empty";
```

```tsx
<Empty>
  <EmptyHeader>
    <EmptyTitle>No recordings yet</EmptyTitle>
    <EmptyDescription>
      Recordings you make in the Studio show up here.
    </EmptyDescription>
  </EmptyHeader>
</Empty>
```

## Anatomy

```tsx
<Empty>
  <EmptyHeader>
    <EmptyTitle />
    <EmptyDescription />
  </EmptyHeader>
  <EmptyContent />
</Empty>
```

## Examples

### Description only

When a list is empty only because of a filter or a search, the description alone is enough. The pane or list it sits in sets the space around it.

```tsx title="components/examples/empty-description.tsx"
"use client";

import { Empty, EmptyDescription, EmptyHeader } from "@/components/ui/empty";

const EmptyDescriptionExample = () => (
  <div className="rounded-row flex h-40 w-full max-w-sm border">
    <Empty>
      <EmptyHeader>
        <EmptyDescription>No messages match these filters.</EmptyDescription>
      </EmptyHeader>
    </Empty>
  </div>
);

export default EmptyDescriptionExample;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `text-sm`, `text-muted-foreground` | The description: 14 px secondary text |
| `text-sm font-medium` | The title: 14 px at weight 500, never larger |
| `gap-3`, `p-6` | The only spacing it brings; it has no radius or border of its own |

## Accessibility

`EmptyTitle` is a `<div>`. When the empty state is what the page is about, put a heading inside it (`<EmptyTitle><h2>…</h2></EmptyTitle>`). An action in `EmptyContent` is an ordinary button or link with its own name.

## API reference

Every part takes every `<div>` prop. Unlike shadcn/ui's Empty there is no `EmptyMedia`: Videorc's empty states are words only.

# Fader (/docs/components/fader)

```tsx title="components/examples/fader-demo.tsx"
"use client";

import { useState } from "react";

import {
  Fader,
  FaderLabel,
  FaderRange,
  FaderReset,
  FaderScale,
  FaderThumb,
  FaderTrack,
  FaderValue,
} from "@/components/ui/fader";

const FaderDemo = () => {
  const [volumeDb, setVolumeDb] = useState(-6);

  return (
    <Fader className="max-w-sm" onValueChange={setVolumeDb} value={volumeDb}>
      <div className="flex items-center gap-2">
        <FaderLabel className="mr-auto">Microphone</FaderLabel>
        <FaderReset />
        <FaderValue />
      </div>
      <FaderTrack>
        <FaderRange />
        <FaderThumb />
      </FaderTrack>
      <FaderScale />
    </Fader>
  );
};

export default FaderDemo;
```

This is a fork of [audiocn's Fader](https://audiocn.dev/docs/components/fader) (MIT). Its behaviour, parts and props are upstream's; only the paint differs:

- The range is `chrome-fill`, not `bg-primary`.
- The default thumb is a `chrome-bead` on the knob's hairline rim (`ring-knob-ring`), like every Videorc slider.
- The console thumb's cap is `rounded-chip`, and the value, its editor and Reset sit on `rounded-row`.

## Installation

```npm
npx shadcn@latest add @videorc/fader
```

The fader builds on audiocn's core (`@audiocn/core`, `@audiocn/use-audio-config` and `@audiocn/db-scale`), so add the `@audiocn` namespace to `components.json` as well:

```json title="components.json"
{
  "registries": {
    "@videorc": "https://ui.videorc.com/r/{name}.json",
    "@audiocn": "https://audiocn.dev/r/{name}.json"
  }
}
```

## Usage

```tsx
import {
  Fader,
  FaderLabel,
  FaderRange,
  FaderThumb,
  FaderTrack,
  FaderValue,
} from "@/components/ui/fader";
```

```tsx
const [volumeDb, setVolumeDb] = useState(0);

<Fader onValueChange={setVolumeDb} value={volumeDb}>
  <FaderLabel>Microphone</FaderLabel>
  <FaderValue />
  <FaderTrack>
    <FaderRange />
    <FaderThumb />
  </FaderTrack>
</Fader>;
```

The value is always in dB. The taper decides where each value sits on the travel. The thumb snaps to its detents (0 dB by default) while dragging, and double-clicking it resets.

## Anatomy

```tsx
<Fader>
  <FaderLabel />
  <FaderReset />
  <FaderValue />
  <FaderTrack>
    <FaderRange />
    <FaderThumb />
  </FaderTrack>
  <FaderScale />
</Fader>
```

`FaderTrack` takes any children, so a level meter can sit inside it.

## Examples

### Bipolar gain

Videorc's Gain faders: `origin={0}` grows the fill from the middle, whole-dB steps, a detent at 0 dB and a value you can type into.

```tsx title="components/examples/fader-gain.tsx"
"use client";

import { useState } from "react";

import {
  Fader,
  FaderLabel,
  FaderRange,
  FaderReset,
  FaderScale,
  FaderThumb,
  FaderTrack,
  FaderValue,
} from "@/components/ui/fader";

const GAIN_DETENTS = [0];
const GAIN_TICKS = [-24, -12, 0, 12, 24];

const FaderGain = () => {
  const [gainDb, setGainDb] = useState(0);

  return (
    <Fader
      className="max-w-sm"
      detents={GAIN_DETENTS}
      fineStep={1}
      largeStep={6}
      max={24}
      min={-24}
      onValueChange={setGainDb}
      origin={0}
      step={1}
      value={gainDb}
    >
      <div className="flex items-center gap-2">
        <FaderLabel className="mr-auto">Microphone gain</FaderLabel>
        <FaderReset />
        <FaderValue editable />
      </div>
      <FaderTrack>
        <FaderRange />
        <FaderThumb />
      </FaderTrack>
      <FaderScale ticks={GAIN_TICKS} />
    </Fader>
  );
};

export default FaderGain;
```

### Console faders

Vertical faders with `variant="console"` and `taper="audio"`, which gives more travel around 0 dB, like a mixing console.

```tsx title="components/examples/fader-console.tsx"
"use client";

import { useState } from "react";

import {
  Fader,
  FaderLabel,
  FaderRange,
  FaderScale,
  FaderThumb,
  FaderTrack,
  FaderValue,
} from "@/components/ui/fader";

const CHANNELS = ["Mic", "System", "Camera"] as const;

type Channel = (typeof CHANNELS)[number];

const FaderConsole = () => {
  const [levels, setLevels] = useState<Record<Channel, number>>({
    Camera: -18,
    Mic: 0,
    System: -12,
  });

  return (
    <div className="flex h-64 gap-6">
      {CHANNELS.map((channel) => (
        <Fader
          className="flex-col items-center"
          key={channel}
          onValueChange={(value) =>
            setLevels((current) => ({ ...current, [channel]: value }))
          }
          orientation="vertical"
          taper="audio"
          value={levels[channel]}
          variant="console"
        >
          <FaderValue />
          <div className="flex min-h-0 flex-1 gap-1">
            <FaderTrack>
              <FaderRange />
              <FaderThumb />
            </FaderTrack>
            <FaderScale />
          </div>
          <FaderLabel>{channel}</FaderLabel>
        </Fader>
      ))}
    </div>
  );
};

export default FaderConsole;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `chrome-fill` | The range |
| `bg-input/90` | The track |
| `chrome-bead` | The default thumb |
| `ring-knob-ring` | The default thumb's hairline rim; a 4 px ring on hover, focus and drag |
| `rounded-chip` | The console thumb's cap |
| `rounded-row` | The value, its editor and Reset |
| `--fader-track-size`, `--fader-thumb-size` | Set by `size` |
| `data-orientation`, `data-variant`, `data-size` | The current settings |
| `data-dragging` | The thumb is held |
| `data-at-detent` | The value sits on a detent |
| `data-silent` | The value is `-Infinity` |
| `data-disabled` | Dims to 50% |
| `data-slot` | `fader`, `fader-label`, `fader-control`, `fader-track`, `fader-range`, `fader-thumb`, `fader-scale`, `fader-value`, `fader-value-input`, `fader-reset` |

## Keyboard

| Key | Action |
| --- | --- |
| <kbd>←</kbd> <kbd>→</kbd> <kbd>↑</kbd> <kbd>↓</kbd> | Changes the value by `step` |
| <kbd>Shift</kbd> with an arrow, <kbd>Page Up</kbd> <kbd>Page Down</kbd> | Changes it by `largeStep` |
| <kbd>Alt</kbd> with an arrow | Changes it by `fineStep` |
| <kbd>Home</kbd> <kbd>End</kbd> | Moves to the minimum (or silence) or the maximum |

Holding <kbd>Alt</kbd> while dragging uses `fineStep` too.

## Accessibility

The thumb holds a native range input with `role="slider"`, and its `aria-valuetext` is the formatted value, such as "−6.0 dB" or "Silent". Name the fader with `FaderLabel` or `aria-label`. The editable value's input is named "Value in dB".

## API reference

### Fader

Every [Base UI Slider](https://base-ui.com/react/components/slider) root prop, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | — | The value in dB. |
| `defaultValue` | `number` | `resetValue` | — |
| `onValueChange` | `(value, details) => void` | — | details.reason is drag, track-press, keyboard, wheel, reset or input. |
| `onValueCommitted` | `(value) => void` | — | Fires when a drag ends, after keyboard input and on reset. |
| `min` | `number` | `-60` | — |
| `max` | `number` | `6` | — |
| `step` | `number` | `0.5` | Arrow keys and drag resolution. |
| `largeStep` | `number` | `6` | Shift with an arrow, Page Up and Page Down. |
| `fineStep` | `number` | `0.1` | Alt with an arrow, and Alt while dragging. |
| `resetValue` | `number` | `0` | Restored by double-click and FaderReset. |
| `taper` | `"linear" \| "audio" \| Taper` | `"linear"` | The position law. |
| `origin` | `number` | `min` | Where the range fill starts. |
| `detents` | `number[]` | `[0]` | Values the thumb snaps to while dragging. |
| `silenceAtMin` | `boolean` | `false` | The lowest position reports -Infinity. |
| `allowWheel` | `boolean` | `false` | The wheel changes the value while the fader is focused. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | — |
| `variant` | `"default" \| "console"` | `"default"` | console has a wide cap thumb. |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` | — |
| `format` | `(db: number) => string` | — | Used by FaderValue and assistive technology. |
| `disabled` | `boolean` | `false` | — |

### FaderValue

The value is as wide as the longest text the fader's range can show, and right-aligned, so moving the fader never shifts the layout. The editor opens at the same width.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `editable` | `boolean` | `false` | Click to type a value. Accepts "-6", "−6 dB" and "-inf". |

### FaderScale

Takes [audiocn's DbScale](https://audiocn.dev/docs/components/db-scale) props. The range, taper and orientation come from the fader.

# Field (/docs/components/field)

```tsx title="components/examples/field-demo.tsx"
"use client";

import { useState } from "react";

import {
  Field,
  FieldContent,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldLegend,
  FieldSet,
} from "@/components/ui/field";
import { Input } from "@/components/ui/input";
import { Switch } from "@/components/ui/switch";
import { Textarea } from "@/components/ui/textarea";

const TITLE_MAX = 100;

const FieldDemo = () => {
  const [title, setTitle] = useState("Friday night speedruns");
  return (
    <FieldSet className="w-full max-w-sm">
      <FieldLegend>Stream details</FieldLegend>
      <FieldGroup>
        <Field>
          <div className="flex items-baseline justify-between gap-2">
            <FieldLabel>Title</FieldLabel>
            <span
              aria-hidden
              className="text-meta text-muted-foreground tabular-nums"
            >
              {title.length}/{TITLE_MAX}
            </span>
          </div>
          <Input
            maxLength={TITLE_MAX}
            onChange={(event) => setTitle(event.target.value)}
            placeholder="Untitled livestream"
            value={title}
          />
        </Field>
        <Field>
          <FieldLabel>Description</FieldLabel>
          <Textarea placeholder="Optional" />
        </Field>
        <Field orientation="horizontal">
          <FieldContent>
            <FieldLabel>Made for kids</FieldLabel>
            <FieldDescription>
              YouTube asks every stream to say whether it&apos;s made for kids.
            </FieldDescription>
          </FieldContent>
          <Switch />
        </Field>
      </FieldGroup>
    </FieldSet>
  );
};

export default FieldDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/field
```

This brings `field-context`, the module every form control reads to find its Field.

## Usage

```tsx
import {
  Field,
  FieldDescription,
  FieldError,
  FieldGroup,
  FieldLabel,
  SettingsRow,
} from "@/components/ui/field";
```

```tsx
<Field>
  <FieldLabel>Stream title</FieldLabel>
  <Input placeholder="Untitled livestream" />
  <FieldDescription>Shown on YouTube and Twitch.</FieldDescription>
</Field>
```

## Anatomy

```tsx
<FieldSet>
  <FieldLegend />
  <FieldGroup>
    <Field>
      <FieldLabel />
      {/* the control */}
      <FieldDescription />
      <FieldError />
    </Field>
    <FieldSeparator />
    <Field orientation="horizontal">
      <FieldContent>
        <FieldLabel />
        <FieldDescription />
      </FieldContent>
      {/* the control */}
    </Field>
  </FieldGroup>
</FieldSet>

<FieldGroup variant="grouped">
  <SettingsRow label="…" description="…" error="…">
    {/* the control */}
  </SettingsRow>
</FieldGroup>
```

## Examples

### Settings rows

A settings page is a `FieldGroup variant="grouped"` of `SettingsRow`s: one inset group split by hairlines, each row with its label and 12 px description on the left and its control on the right. `error` puts the row's own refusal or failure under the description. A row whose control is a button names its group with `aria-label`, since a label can't name a button.

```tsx title="components/examples/field-settings-row.tsx"
"use client";

import { useState } from "react";

import { FolderIcon } from "@/components/icons";
import { Button } from "@/components/ui/button";
import { FieldGroup, SettingsRow } from "@/components/ui/field";
import { Switch } from "@/components/ui/switch";

const FieldSettingsRow = () => {
  const [saveLocal, setSaveLocal] = useState(true);
  const [chatInStudio, setChatInStudio] = useState(false);
  return (
    <FieldGroup className="max-w-lg" variant="grouped">
      <SettingsRow
        aria-label="Recordings folder"
        description="~/Movies/Videorc"
        error="The recordings folder you chose isn't available."
        label="Recordings folder"
      >
        <Button variant="outline">
          <FolderIcon data-icon="inline-start" />
          Choose…
        </Button>
      </SettingsRow>
      <SettingsRow
        description="Keep a copy on this computer while you stream."
        label="Save local recording"
      >
        <Switch checked={saveLocal} onCheckedChange={setSaveLocal} />
      </SettingsRow>
      <SettingsRow
        description="Show chat under Session while you're on air."
        label="Chat in Studio"
      >
        <Switch checked={chatInStudio} onCheckedChange={setChatInStudio} />
      </SettingsRow>
    </FieldGroup>
  );
};

export default FieldSettingsRow;
```

### Choice cards

Wrap a horizontal Field in a `FieldLabel` to make the whole card the checkbox's label: a click anywhere toggles it, and the card shows the focus ring. `data-slot="checkbox-group"` on the FieldGroup tightens the gap.

```tsx title="components/examples/field-choice-card.tsx"
"use client";

import { Checkbox } from "@/components/ui/checkbox";
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldTitle,
} from "@/components/ui/field";

const DESTINATIONS = [
  { checked: true, detail: "Public · 1080p60", name: "YouTube" },
  { checked: false, detail: "Just Chatting · 6,000 kbps", name: "Twitch" },
];

const FieldChoiceCard = () => (
  <FieldGroup className="max-w-sm" data-slot="checkbox-group">
    {DESTINATIONS.map((destination) => (
      <FieldLabel key={destination.name}>
        <Field orientation="horizontal">
          <Checkbox defaultChecked={destination.checked} />
          <FieldContent>
            <FieldTitle>{destination.name}</FieldTitle>
            <FieldDescription>{destination.detail}</FieldDescription>
          </FieldContent>
        </Field>
      </FieldLabel>
    ))}
  </FieldGroup>
);

export default FieldChoiceCard;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `rounded-row`, `bg-inset`, `divide-border` | The grouped variant: one inset group split by hairlines |
| `text-meta`, `text-muted-foreground` | Descriptions, at 12 px in the secondary tier |
| `text-foreground`, `text-destructive` | An error: monochrome words, the error glyph in the destructive tone |
| `data-orientation` | `vertical`, `horizontal` or `responsive` on a Field |
| `data-variant` | `default` or `grouped` on a FieldGroup |
| `data-settings-row` | Marks a SettingsRow's Field |
| `data-disabled="true"` | On a Field, dims its label |

## Accessibility

### Naming and describing

A Field names its control. Each control and the `FieldLabel` register an id with the Field when they mount (an explicit `id` always wins), and then:

- the label points `htmlFor` at the first control a label element can name: an [Input](/docs/components/input), a [Textarea](/docs/components/textarea), a [Switch](/docs/components/switch) or a [Checkbox](/docs/components/checkbox);
- a control no label element can point at, such as a [Slider](/docs/components/slider) thumb or a group of toggles, takes the label through `aria-labelledby`, unless it has an `aria-label` of its own;
- every `FieldDescription` describes the Field's controls through `aria-describedby`, unless a control passes its own.

Nothing points at an id that isn't on the page, two controls in one Field never share an id, and outside a Field nothing is added. So a SettingsRow's label names its switch and its description describes it, with no ids at all.

A `FieldError` is a `role="alert"`, so it is announced when it appears. Mark the control `aria-invalid` too.

### Your own controls

The wiring lives in `components/ui/field-context.ts`, its own module so a control can read it without pulling the Field's styles into its bundle. A control of your own joins in with the same hooks:

```tsx
"use client";

import type { ComponentProps } from "react";

import {
  useFieldControlId,
  useFieldDescribedBy,
} from "@/components/ui/field-context";

function ColorWell({
  id,
  "aria-describedby": ariaDescribedBy,
  ...props
}: ComponentProps<"input">) {
  const controlId = useFieldControlId(id);
  const describedBy = useFieldDescribedBy(ariaDescribedBy);
  return (
    <input
      aria-describedby={describedBy}
      id={controlId}
      type="color"
      {...props}
    />
  );
}
```

## API reference

Each part takes every attribute of the element it renders, plus:

### FieldGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "grouped"` | `"default"` | grouped draws one inset group with hairlines between its Fields. |

### Field

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"vertical" \| "horizontal" \| "responsive"` | `"vertical"` | responsive is vertical until its FieldGroup is wide enough. |

### FieldLabel

A [Label](/docs/components/label).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `htmlFor` | `string` | `the Field's first control` | Points at a control by id. Leave it out inside a Field. |
| `id` | `string` | `made inside a Field` | — |

### FieldDescription

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | `made inside a Field` | Describes the Field's controls. |

### FieldError

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `errors` | `({ message?: string } \| undefined)[]` | — | Shown when there are no children: one message, or a list of distinct ones. |

### FieldLegend

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"legend" \| "label"` | `"legend"` | label is 14 px. |

### SettingsRow

Every Field prop except `orientation`, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `ReactNode` | — | The row's FieldLabel. |
| `description` | `ReactNode` | — | A FieldDescription under the label. |
| `error` | `ReactNode` | — | A FieldError under the description, announced when it appears. |
| `children` | `ReactNode` | — | The control, on the right. |

### field-context

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `useFieldControlId(id?)` | `string \| undefined` | — | A control a label can name: its id, made and registered inside a Field. |
| `useFieldDescribedBy(ariaDescribedBy?)` | `string \| undefined` | — | The control's own aria-describedby, else its Field's descriptions. |
| `useFieldLabelledBy(ariaLabelledBy?, ariaLabel?)` | `string \| undefined` | — | For a control no label can point at: its own, else the FieldLabel's id unless it has an aria-label. |
| `useFieldLabelIds(id?)` | `{ id?, htmlFor? }` | — | FieldLabel's side: its id and the control it points at. |
| `useFieldDescriptionId(id?)` | `string \| undefined` | — | FieldDescription's side: its id, registered with the Field. |
| `useFieldIds()` | `FieldIds` | — | Field's side: the registry it provides through FieldIdsContext. |

# Hover Card (/docs/components/hover-card)

```tsx title="components/examples/hover-card-demo.tsx"
"use client";

import { TwitchIcon } from "@/components/icons";
import {
  HoverCard,
  HoverCardContent,
  HoverCardTrigger,
} from "@/components/ui/hover-card";

const HoverCardDemo = () => (
  <p className="text-sm">
    Streaming to{" "}
    <HoverCard>
      <HoverCardTrigger
        closeDelay={80}
        delay={400}
        href="https://www.twitch.tv"
        rel="noopener noreferrer"
        target="_blank"
      >
        <span className="font-medium underline-offset-4 hover:underline">
          Twitch
        </span>
      </HoverCardTrigger>
      <HoverCardContent align="start">
        <div className="flex gap-3">
          <TwitchIcon className="text-platform-twitch-ink size-5 shrink-0" />
          <div className="flex flex-col gap-1">
            <p className="font-medium">orcdev on Twitch</p>
            <p className="text-meta text-muted-foreground">
              Live for 1:12:04 at 6,000 kbps, with no dropped frames.
            </p>
          </div>
        </div>
      </HoverCardContent>
    </HoverCard>
  </p>
);

export default HoverCardDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/hover-card
```

## Usage

```tsx
import {
  HoverCard,
  HoverCardContent,
  HoverCardTrigger,
} from "@/components/ui/hover-card";
```

```tsx
<HoverCard>
  <HoverCardTrigger href="https://www.twitch.tv">Twitch</HoverCardTrigger>
  <HoverCardContent>Live for 1:12:04 at 6,000 kbps.</HoverCardContent>
</HoverCard>
```

The trigger is a link. Set how long it waits with `delay` and `closeDelay` on the trigger: a status bar's destinations use 400 ms and 80 ms, so the cards keep up as the pointer runs along the bar.

## Anatomy

```tsx
<HoverCard>
  <HoverCardTrigger />
  <HoverCardContent />
</HoverCard>
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `glass-float` | The popup tier: the window's solid tone, a 1 px rim and the float drop |
| `rounded-lg` | The popup tier's 10 px corners |
| `w-72`, `p-3` | Its default width and padding |
| `data-open`, `data-closed` | Fades and scales from 0.98 in 100 ms, with no slide |

## Keyboard

| Key      | Action                              |
| -------- | ----------------------------------- |
| `Tab`    | Focusing the trigger opens the card |
| `Escape` | Closes the card                     |

## Accessibility

The card is a sighted user's preview. Keyboard and screen reader users reach the link, not the card, so never put the only copy of a fact or an action in it.

## API reference

Every [Base UI Preview Card](https://base-ui.com/react/components/preview-card) prop, plus:

### HoverCardTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `delay` | `number` | `600` | Milliseconds before the card opens. |
| `closeDelay` | `number` | `300` | Milliseconds before the card closes. |

### HoverCardContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | — |
| `sideOffset` | `number` | `4` | — |
| `align` | `"start" \| "center" \| "end"` | `"center"` | — |
| `alignOffset` | `number` | `0` | — |

# Components (/docs/components)

Each component is a shadcn/ui component customised to Videorc's design language, or one of Videorc's own controls built the same way. Install any of them with the shadcn CLI after adding the [registry](/docs/installation).

# Info Tooltip (/docs/components/info-tooltip)

```tsx title="components/examples/info-tooltip-demo.tsx"
"use client";

import { Badge } from "@/components/ui/badge";
import { InfoTooltip } from "@/components/ui/info-tooltip";

const InfoTooltipDemo = () => (
  <div className="flex items-center gap-2">
    <InfoTooltip content="The disk is full. Free up space, then export again.">
      <Badge variant="destructive">MP4 failed</Badge>
    </InfoTooltip>
    <InfoTooltip content="Twitch dropped 2% of frames in the last minute.">
      <Badge variant="warning">Dropped frames</Badge>
    </InfoTooltip>
  </div>
);

export default InfoTooltipDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/info-tooltip
```

## Usage

```tsx
import { InfoTooltip } from "@/components/ui/info-tooltip";
```

```tsx
<InfoTooltip content="The disk is full.">
  <Badge variant="destructive">MP4 failed</Badge>
</InfoTooltip>
```

## Examples

### On a control

A control that takes focus itself (a button whose outcome needs a sentence) is the trigger and is described, with no wrapper: pass `focusable={false}`. A plain hint on a control is a [Tooltip](/docs/components/tooltip); a disabled control's reason is a [Disabled reason](/docs/components/disabled-reason).

```tsx title="components/examples/info-tooltip-control.tsx"
"use client";

import { ExternalLinkIcon } from "@/components/icons";
import { Button } from "@/components/ui/button";
import { InfoTooltip } from "@/components/ui/info-tooltip";

const InfoTooltipControl = () => (
  <InfoTooltip
    content="Opens x.com to approve live broadcasting for this account."
    focusable={false}
  >
    <Button variant="secondary">
      Authorize X Live
      <ExternalLinkIcon data-icon="inline-end" />
    </Button>
  </InfoTooltip>
);

export default InfoTooltipControl;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `rounded-chip`, `focus-visible:ring-3` | The wrapper's focus ring, around the chip |
| `data-slot="info-tooltip"` | The focusable wrapper |
| `data-slot="info-tooltip-text"` | The hidden description |

The tooltip itself is the registry's [Tooltip](/docs/components/tooltip).

## Keyboard

| Key            | Action                                     |
| -------------- | ------------------------------------------ |
| <kbd>Tab</kbd> | Focuses the chip and shows the explanation |
| <kbd>Esc</kbd> | Hides it                                   |

## Accessibility

A badge isn't focusable, so a `title` on it never reaches the keyboard or a screen reader. The wrapper is a tab stop, and the explanation stays in the DOM, hidden, as its `aria-describedby`, not only while the tooltip shows. Base UI's tooltip is visual only, so this description is what a screen reader hears. Pass `tabIndex={-1}` for a chip in a roving-focus row that isn't the active one. With no `content` the child renders exactly as it is.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `content` | `ReactNode` | — | The explanation in a sentence; null or empty for none. |
| `children` | `ReactElement` | — | The chip, dot or word it explains. |
| `focusable` | `boolean` | `true` | False when the child is a control that takes focus itself. |
| `tabIndex` | `number` | `0` | The wrapper's tab stop. |
| `className` | `string` | — | Layout for the wrapper (shrink-0, min-w-0), never styling. |
| `side` | `"top" \| "bottom" \| "left" \| "right"` | `"top"` | — |
| `align` | `"start" \| "center" \| "end"` | `"center"` | — |

# Input Group (/docs/components/input-group)

```tsx title="components/examples/input-group-demo.tsx"
"use client";

import { SearchIcon } from "@/components/icons";
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
  InputGroupText,
} from "@/components/ui/input-group";

const InputGroupDemo = () => (
  <InputGroup className="max-w-sm">
    <InputGroupInput
      aria-label="Search recordings"
      placeholder="Search recordings…"
    />
    <InputGroupAddon>
      <SearchIcon />
    </InputGroupAddon>
    <InputGroupAddon align="inline-end">
      <InputGroupText>12 results</InputGroupText>
    </InputGroupAddon>
  </InputGroup>
);

export default InputGroupDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/input-group
```

## Usage

```tsx
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupInput,
  InputGroupText,
  InputGroupTextarea,
} from "@/components/ui/input-group";
```

```tsx
<InputGroup>
  <InputGroupInput
    aria-label="Search recordings"
    placeholder="Search recordings…"
  />
  <InputGroupAddon>
    <SearchIcon />
  </InputGroupAddon>
</InputGroup>
```

## Anatomy

```tsx
<InputGroup>
  <InputGroupInput /> {/* or <InputGroupTextarea /> */}
  <InputGroupAddon align="inline-start | inline-end | block-start | block-end">
    <InputGroupText />
    <InputGroupButton />
  </InputGroupAddon>
</InputGroup>
```

An addon's place comes from `align`, not from where it sits in the markup: write the input first, then its addons.

## Examples

### Buttons

`InputGroupButton` is a ghost [Button](/docs/components/button) at the one compact size, so it sits inside the 28 px field. Use `xs` for a word (Copy) and `icon-xs` for an icon alone (Clear search).

```tsx title="components/examples/input-group-button.tsx"
"use client";

import { useState } from "react";

import { CheckIcon, CloseIcon, CopyIcon, SearchIcon } from "@/components/icons";
import { Field, FieldGroup, FieldLabel } from "@/components/ui/field";
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupInput,
} from "@/components/ui/input-group";

const InputGroupButtonExample = () => {
  const [copied, setCopied] = useState(false);
  const [query, setQuery] = useState("raid");
  return (
    <FieldGroup className="max-w-sm">
      <Field>
        <FieldLabel>Server URL</FieldLabel>
        <InputGroup>
          <InputGroupInput readOnly value="rtmp://live.twitch.tv/app" />
          <InputGroupAddon align="inline-end">
            <InputGroupButton onClick={() => setCopied(true)}>
              {copied ? <CheckIcon /> : <CopyIcon />}
              {copied ? "Copied" : "Copy"}
            </InputGroupButton>
          </InputGroupAddon>
        </InputGroup>
      </Field>
      <InputGroup>
        <InputGroupInput
          aria-label="Search chat"
          onChange={(event) => setQuery(event.target.value)}
          placeholder="Search chat…"
          value={query}
        />
        <InputGroupAddon>
          <SearchIcon />
        </InputGroupAddon>
        {query ? (
          <InputGroupAddon align="inline-end">
            <InputGroupButton
              aria-label="Clear search"
              onClick={() => setQuery("")}
              size="icon-xs"
            >
              <CloseIcon />
            </InputGroupButton>
          </InputGroupAddon>
        ) : null}
      </InputGroup>
    </FieldGroup>
  );
};

export default InputGroupButtonExample;
```

### Textarea

With `InputGroupTextarea` the group grows to fit, and a `block-end` addon becomes the field's footer: a counter and the send button of a chat composer.

```tsx title="components/examples/input-group-textarea.tsx"
"use client";

import { useState } from "react";

import { SendIcon } from "@/components/icons";
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupText,
  InputGroupTextarea,
} from "@/components/ui/input-group";

const MAX_CHARACTERS = 200;

const InputGroupTextareaExample = () => {
  const [message, setMessage] = useState("");
  return (
    <InputGroup className="max-w-sm">
      <InputGroupTextarea
        aria-label="Message"
        maxLength={MAX_CHARACTERS}
        onChange={(event) => setMessage(event.target.value)}
        placeholder="Say something on stream"
        value={message}
      />
      <InputGroupAddon align="block-end">
        <InputGroupText>
          <span className="tabular-nums">
            {message.length}/{MAX_CHARACTERS}
          </span>
        </InputGroupText>
        <InputGroupButton
          className="ml-auto"
          disabled={message.trim().length === 0}
          onClick={() => setMessage("")}
          variant="default"
        >
          <SendIcon />
          Send
        </InputGroupButton>
      </InputGroupAddon>
    </InputGroup>
  );
};

export default InputGroupTextareaExample;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `h-control` | The 28 px group height; `h-auto` with a textarea or a block addon |
| `rounded-chip` | The 6 px control radius |
| `bg-input/50` | The recessed field fill, on the group |
| `data-align` | The addon's place: `inline-start`, `inline-end`, `block-start`, `block-end` |
| `data-disabled="true"` on the group | Dims the addons |
| `data-slot` | `input-group`, `input-group-addon`, `input-group-text`, `input-group-control` |

## Accessibility

The group is a `role="group"`. Name the input itself: an `aria-label`, or a `FieldLabel` when the group sits in a [Field](/docs/components/field). An icon-only `InputGroupButton` needs an `aria-label`. A click on an addon's text or icon focuses the input; a click on its button doesn't.

## API reference

### InputGroup

Every `<div>` attribute.

### InputGroupAddon

Every `<div>` attribute, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"inline-start" \| "inline-end" \| "block-start" \| "block-end"` | `"inline-start"` | Where the addon sits: before or after the input, or above or below it. |

### InputGroupButton

Every [Button](/docs/components/button) prop, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"xs" \| "icon-xs"` | `"xs"` | 24 px: a word, or an icon alone. |
| `variant` | `Button variant` | `"ghost"` | — |
| `type` | `"button" \| "submit" \| "reset"` | `"button"` | — |

### InputGroupInput, InputGroupTextarea

Every [Input](/docs/components/input) or [Textarea](/docs/components/textarea) prop, drawn borderless inside the group.

### InputGroupText

Every `<span>` attribute.

# Input (/docs/components/input)

```tsx title="components/examples/input-demo.tsx"
"use client";

import { Field, FieldLabel } from "@/components/ui/field";
import { Input } from "@/components/ui/input";

const InputDemo = () => (
  <Field className="max-w-sm">
    <FieldLabel>Stream title</FieldLabel>
    <Input placeholder="Untitled livestream" />
  </Field>
);

export default InputDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/input
```

## Usage

```tsx
import { Input } from "@/components/ui/input";
```

```tsx
<Input aria-label="Stream title" placeholder="Untitled livestream" />
```

Inside a [Field](/docs/components/field), leave out the id: the Field gives the input one and points its `FieldLabel` at it.

```tsx
<Field>
  <FieldLabel>Stream title</FieldLabel>
  <Input placeholder="Untitled livestream" />
</Field>
```

## Examples

### States

Set `aria-invalid` and put a `FieldError` under the input when its value is refused: the ring turns destructive and the error is announced. A disabled input inside a Field says why in its description.

```tsx title="components/examples/input-states.tsx"
"use client";

import {
  Field,
  FieldDescription,
  FieldError,
  FieldGroup,
  FieldLabel,
} from "@/components/ui/field";
import { Input } from "@/components/ui/input";

const InputStates = () => (
  <FieldGroup className="max-w-sm">
    <Field>
      <FieldLabel>Output width</FieldLabel>
      <Input aria-invalid defaultValue="1919" inputMode="numeric" />
      <FieldError>Width must be even.</FieldError>
    </Field>
    <Field data-disabled="true">
      <FieldLabel>Recordings folder</FieldLabel>
      <Input defaultValue="~/Movies/Videorc" disabled />
      <FieldDescription>
        Locked while you&apos;re recording or live.
      </FieldDescription>
    </Field>
  </FieldGroup>
);

export default InputStates;
```

### File

`type="file"` styles the button inside the field to match the text around it.

```tsx title="components/examples/input-file.tsx"
"use client";

import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";
import { Input } from "@/components/ui/input";

const InputFile = () => (
  <Field className="max-w-sm">
    <FieldLabel>Thumbnail</FieldLabel>
    <Input accept="image/png,image/jpeg" type="file" />
    <FieldDescription>A 1280 × 720 PNG or JPEG, up to 2 MB.</FieldDescription>
  </Field>
);

export default InputFile;
```

## Theming

| Token or attribute  | Meaning                                      |
| ------------------- | -------------------------------------------- |
| `h-control`         | The 28 px desktop control height             |
| `rounded-chip`      | The 6 px control radius                      |
| `bg-input/50`       | The recessed field fill                      |
| `text-sm`           | 14 px at every width, never the mobile 16 px |
| `aria-invalid`      | Draws the destructive border and ring        |
| `data-slot="input"` | The input, for styling from a parent         |

## Accessibility

Every input needs a name. Inside a Field, the `FieldLabel` is its name and every `FieldDescription` describes it through `aria-describedby`. Outside one, pass `aria-label`, or a [Label](/docs/components/label) with `htmlFor`. An explicit `id` or `aria-describedby` always wins over the Field's.

The input is 14 px at every width. Mobile Safari zooms into a field under 16 px, but Videorc is a desktop app, and a 16 px field would sit taller than every control beside it.

## API reference

Every `<input>` attribute, rendered through [Base UI Input](https://base-ui.com/react/components/input), plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | — | Kept as given. Inside a Field, one is made when it is missing, and the FieldLabel points at it. |
| `aria-describedby` | `string` | — | Replaces the Field's descriptions. |

# Kbd (/docs/components/kbd)

```tsx title="components/examples/kbd-demo.tsx"
"use client";

import { Kbd, KbdGroup } from "@/components/ui/kbd";

const KbdDemo = () => (
  <div className="text-muted-foreground flex flex-col gap-2 text-sm">
    <p className="flex items-center gap-2">
      <KbdGroup>
        <Kbd>↑</Kbd>
        <Kbd>↓</Kbd>
      </KbdGroup>
      Move between questions
    </p>
    <p className="flex items-center gap-2">
      <Kbd>Esc</Kbd>
      Dismiss Buddy’s proposed post
    </p>
  </div>
);

export default KbdDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/kbd
```

## Usage

```tsx
import { Kbd, KbdGroup } from "@/components/ui/kbd";
```

```tsx
<Kbd>Esc</Kbd>
```

Kbd draws a key. A shortcut goes through [Shortcut keys](/docs/components/shortcut-keys), which prints it the way the reader's platform does and draws this chip: never type a modifier glyph or "Cmd+" by hand.

## Examples

### In a button

Inside a `default`, `destructive` or `record` button the gray keycap reads at under 3:1, so there the chip takes the button's text colour on a faint fill of it, with no glass. It matches by ancestry: nothing to remember at the call site.

```tsx title="components/examples/kbd-in-button.tsx"
"use client";

import { Button } from "@/components/ui/button";
import { Kbd } from "@/components/ui/kbd";
import { ShortcutKeys } from "@/components/ui/shortcut-keys";

const KbdInButton = () => (
  <div className="flex flex-wrap items-center gap-2">
    <Button variant="secondary">
      Cancel
      <Kbd>Esc</Kbd>
    </Button>
    <Button>
      Go live
      <ShortcutKeys accelerator="CmdOrCtrl+Enter" />
    </Button>
    <Button variant="destructive">
      Dismiss
      <ShortcutKeys accelerator="Backspace" />
    </Button>
  </div>
);

export default KbdInButton;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `glass-keycap` | The keycap: a gradient fill, a rim, a bright top edge and a dark bottom edge |
| `--keycap-fill-top`, `--keycap-fill-bottom`, `--keycap-rim` | The keycap's fill and rim, per theme |
| `--keycap-highlight`, `--keycap-base` | Its top and bottom edges |
| `rounded-chip` | The 6 px chip radius |
| `KBD_ON_FILLED_BUTTON` | The classes for a chip inside a filled button, exported |

## Accessibility

Kbd is a `<kbd>` element, and KbdGroup a `<span>` that spaces several. Screen readers read the text inside, so pair a key with words that say what it does ("Move between questions"), and give a control its shortcut with `aria-keyshortcuts` (`shortcutAriaKeys` from `@/lib/platform`).

## API reference

### Kbd

Every `kbd` prop.

### KbdGroup

Every `span` prop.

# Label (/docs/components/label)

```tsx title="components/examples/label-demo.tsx"
"use client";

import { Checkbox } from "@/components/ui/checkbox";
import { Label } from "@/components/ui/label";

const LabelDemo = () => (
  <div className="flex items-center gap-2">
    <Checkbox id="label-demo-markers" />
    <Label htmlFor="label-demo-markers">Include markers in the export</Label>
  </div>
);

export default LabelDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/label
```

## Usage

```tsx
import { Label } from "@/components/ui/label";
```

```tsx
<div className="flex items-center gap-2">
  <Checkbox id="include-markers" />
  <Label htmlFor="include-markers">Include markers in the export</Label>
</div>
```

Inside a [Field](/docs/components/field), use `FieldLabel` instead: it points at the Field's control on its own.

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `text-sm`, `font-medium` | 14 px, medium weight |
| `peer-disabled` | Dims to 50% beside a disabled `peer` control |
| `data-disabled="true"` on a `group` | Dims and stops pointer events |
| `data-slot="label"` | The label, for styling from a parent |

## Accessibility

Point `htmlFor` at the control's `id`. For a [Checkbox](/docs/components/checkbox) or [Switch](/docs/components/switch), the `id` lands on Base UI's hidden input: a click on the label toggles the control, and Base UI names the control by the label.

## API reference

Every `<label>` attribute.

# Parameter Slider (/docs/components/parameter-slider)

```tsx title="components/examples/parameter-slider-demo.tsx"
"use client";

import { useState } from "react";

import {
  ParameterSlider,
  ParameterSliderControl,
  ParameterSliderDescription,
  ParameterSliderHeader,
  ParameterSliderInput,
  ParameterSliderLabel,
  ParameterSliderReset,
} from "@/components/ui/parameter-slider";

const ParameterSliderDemo = () => {
  const [offsetMs, setOffsetMs] = useState(0);

  return (
    <ParameterSlider
      className="max-w-sm"
      largeStep={5}
      max={1000}
      min={-1000}
      onValueChange={setOffsetMs}
      origin={0}
      resetValue={0}
      step={1}
      unit="ms"
      value={offsetMs}
    >
      <ParameterSliderHeader>
        <ParameterSliderLabel>Microphone sync</ParameterSliderLabel>
        <ParameterSliderReset />
        <ParameterSliderInput />
      </ParameterSliderHeader>
      <ParameterSliderControl />
      <ParameterSliderDescription>
        Moves your voice later (+) or earlier (−) to line up with the video.
      </ParameterSliderDescription>
    </ParameterSlider>
  );
};

export default ParameterSliderDemo;
```

This is a fork of [audiocn's Parameter Slider](https://audiocn.dev/docs/components/parameter-slider) (MIT). Its behaviour, parts and props are upstream's; only the paint differs:

- The range is `chrome-fill`, not `bg-primary`.
- The thumb is a `chrome-bead` on the knob's hairline rim (`ring-knob-ring`), like every Videorc slider.
- Reset sits on `rounded-row`.

## Installation

```npm
npx shadcn@latest add @videorc/parameter-slider
```

The slider builds on audiocn's core (`@audiocn/core` and `@audiocn/use-audio-config`), so add the `@audiocn` namespace to `components.json` as well:

```json title="components.json"
{
  "registries": {
    "@videorc": "https://ui.videorc.com/r/{name}.json",
    "@audiocn": "https://audiocn.dev/r/{name}.json"
  }
}
```

## Usage

```tsx
import {
  ParameterSlider,
  ParameterSliderControl,
  ParameterSliderHeader,
  ParameterSliderInput,
  ParameterSliderLabel,
} from "@/components/ui/parameter-slider";
```

```tsx
<ParameterSlider
  max={1000}
  min={-1000}
  onValueChange={setOffsetMs}
  unit="ms"
  value={offsetMs}
>
  <ParameterSliderHeader>
    <ParameterSliderLabel>Microphone sync</ParameterSliderLabel>
    <ParameterSliderInput />
  </ParameterSliderHeader>
  <ParameterSliderControl />
</ParameterSlider>
```

Use it for gain trims, delays, thresholds, times, frequencies and percentages. For a volume, use [Fader](/docs/components/fader).

## Anatomy

```tsx
<ParameterSlider>
  <ParameterSliderHeader>
    <ParameterSliderLabel />
    <ParameterSliderReset />
    <ParameterSliderInput />
    <ParameterSliderValue />
  </ParameterSliderHeader>
  <ParameterSliderControl />
  <ParameterSliderMarks />
  <ParameterSliderDescription />
</ParameterSlider>
```

## Examples

### Read-only value

Show `ParameterSliderValue` in place of the input when typing a number adds nothing, as for a banner's opacity.

```tsx title="components/examples/parameter-slider-value.tsx"
"use client";

import { useState } from "react";

import {
  ParameterSlider,
  ParameterSliderControl,
  ParameterSliderHeader,
  ParameterSliderLabel,
  ParameterSliderValue,
} from "@/components/ui/parameter-slider";

const ParameterSliderValueExample = () => {
  const [opacity, setOpacity] = useState(85);

  return (
    <ParameterSlider
      className="max-w-sm"
      largeStep={10}
      max={100}
      min={20}
      onValueChange={setOpacity}
      resetValue={100}
      step={1}
      unit="%"
      value={opacity}
    >
      <ParameterSliderHeader>
        <ParameterSliderLabel>Banner opacity</ParameterSliderLabel>
        <ParameterSliderValue />
      </ParameterSliderHeader>
      <ParameterSliderControl />
    </ParameterSlider>
  );
};

export default ParameterSliderValueExample;
```

### Log scale with marks

`scale="log"` gives each octave the same travel, which suits frequencies and times. `marks` labels points along the track.

```tsx title="components/examples/parameter-slider-frequency.tsx"
"use client";

import {
  ParameterSlider,
  ParameterSliderControl,
  ParameterSliderDescription,
  ParameterSliderHeader,
  ParameterSliderLabel,
  ParameterSliderMarks,
  ParameterSliderValue,
} from "@/components/ui/parameter-slider";

const KILOHERTZ = 1000;

const formatHz = (hz: number) =>
  hz >= KILOHERTZ
    ? `${(hz / KILOHERTZ).toFixed(1)} kHz`
    : `${Math.round(hz)} Hz`;

const MARKS = [
  { label: "20", value: 20 },
  { label: "50", value: 50 },
  { label: "100", value: 100 },
  { label: "200", value: 200 },
  { label: "500", value: 500 },
  { label: "1k", value: 1000 },
];

const ParameterSliderFrequency = () => (
  <ParameterSlider
    className="max-w-sm"
    defaultValue={80}
    format={formatHz}
    marks={MARKS}
    max={1000}
    min={20}
    scale="log"
    step={1}
  >
    <ParameterSliderHeader>
      <ParameterSliderLabel>Microphone low cut</ParameterSliderLabel>
      <ParameterSliderValue />
    </ParameterSliderHeader>
    <ParameterSliderControl />
    <ParameterSliderMarks />
    <ParameterSliderDescription>
      Filters out rumble below this frequency, like a desk fan or a footstep.
    </ParameterSliderDescription>
  </ParameterSlider>
);

export default ParameterSliderFrequency;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `chrome-fill` | The range |
| `bg-input/90` | The 4 px track |
| `chrome-bead` | The thumb |
| `ring-knob-ring` | The thumb's hairline rim; a 4 px ring on hover, focus and drag |
| `rounded-row` | Reset |
| `data-modified` | The value differs from `resetValue` |
| `data-disabled` | Dims to 50% |
| `data-slot` | `parameter-slider`, `parameter-slider-header`, `parameter-slider-label`, `parameter-slider-input-group`, `parameter-slider-input`, `parameter-slider-unit`, `parameter-slider-value`, `parameter-slider-reset`, `parameter-slider-control`, `parameter-slider-track`, `parameter-slider-range`, `parameter-slider-thumb`, `parameter-slider-marks`, `parameter-slider-description` |

## Keyboard

| Key | Action |
| --- | --- |
| <kbd>←</kbd> <kbd>→</kbd> <kbd>↑</kbd> <kbd>↓</kbd> | Changes the value by `step` |
| <kbd>Shift</kbd> with an arrow, <kbd>Page Up</kbd> <kbd>Page Down</kbd> | Changes it by `largeStep` |
| <kbd>Home</kbd> <kbd>End</kbd> | Moves to the minimum or maximum |

The number input takes the arrow keys and typing, and dragging the unit beside it scrubs the value.

## Accessibility

- The label names both the slider thumb and the number input.
- `ParameterSliderDescription` describes the thumb.
- The thumb's `aria-valuetext` is the formatted value with its unit.

## API reference

### ParameterSlider

Every `div` prop, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | — | — |
| `defaultValue` | `number` | — | — |
| `onValueChange` | `(value, details) => void` | — | details.reason is drag, keyboard, input or reset. |
| `onValueCommitted` | `(value) => void` | — | Fires when a drag ends, after keyboard input, typing and reset. |
| `min` | `number` | `0` | — |
| `max` | `number` | `100` | — |
| `step` | `number` | `1` | — |
| `largeStep` | `number` | `10` | Shift with an arrow, Page Up and Page Down. |
| `unit` | `string` | — | A suffix such as "ms", "dB", "Hz" or "%". |
| `decimals` | `number` | `from step` | — |
| `scale` | `"linear" \| "log"` | `"linear"` | log suits frequency and time. |
| `origin` | `number` | `min` | Where the fill starts. |
| `resetValue` | `number` | `defaultValue ?? min` | — |
| `marks` | `{ value: number; label?: string }[]` | — | Shown by ParameterSliderMarks. |
| `format` | `(value: number) => string` | — | — |
| `disabled` | `boolean` | `false` | — |

### ParameterSliderInput

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `scrub` | `boolean` | `true` | Drag the unit to change the value. |

# Popover (/docs/components/popover)

```tsx title="components/examples/popover-demo.tsx"
"use client";

import { useState } from "react";

import { MarkerIcon } from "@/components/icons";
import { Button } from "@/components/ui/button";
import { Field, FieldLabel } from "@/components/ui/field";
import { Input } from "@/components/ui/input";
import {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/ui/popover";

const PopoverDemo = () => {
  const [open, setOpen] = useState(false);
  return (
    <Popover onOpenChange={setOpen} open={open}>
      <PopoverTrigger render={<Button variant="secondary" />}>
        <MarkerIcon data-icon="inline-start" />
        Add marker…
      </PopoverTrigger>
      <PopoverContent align="start">
        <PopoverHeader>
          <PopoverTitle>Add a marker</PopoverTitle>
          <PopoverDescription>
            Marks this moment, so you can find it in the recording later.
          </PopoverDescription>
        </PopoverHeader>
        <Field>
          <FieldLabel>Note</FieldLabel>
          <Input defaultValue="Viewer question about the mixer" />
        </Field>
        <Button className="self-end" onClick={() => setOpen(false)}>
          Add marker
        </Button>
      </PopoverContent>
    </Popover>
  );
};

export default PopoverDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/popover
```

## Usage

```tsx
import {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/ui/popover";
```

```tsx
<Popover>
  <PopoverTrigger render={<Button variant="secondary" />}>
    Add marker…
  </PopoverTrigger>
  <PopoverContent>
    <PopoverHeader>
      <PopoverTitle>Add a marker</PopoverTitle>
      <PopoverDescription>
        Marks this moment in the recording.
      </PopoverDescription>
    </PopoverHeader>
  </PopoverContent>
</Popover>
```

## Anatomy

```tsx
<Popover>
  <PopoverAnchor />
  <PopoverTrigger />
  <PopoverContent>
    <PopoverHeader>
      <PopoverTitle />
      <PopoverDescription />
    </PopoverHeader>
  </PopoverContent>
</Popover>
```

## Examples

### Anchor

`PopoverAnchor` wraps what the popover should line up with when that isn't the trigger: here the whole status bar, so the sound board opens over its end rather than over the small Sounds button. The trigger still opens and closes it.

```tsx title="components/examples/popover-anchor.tsx"
"use client";

import { SpeakerOnIcon } from "@/components/icons";
import { Button } from "@/components/ui/button";
import {
  Popover,
  PopoverAnchor,
  PopoverContent,
  PopoverTrigger,
} from "@/components/ui/popover";

const SOUNDS = ["Applause", "Drum roll", "Air horn", "Rimshot"] as const;

const PopoverAnchorExample = () => (
  <Popover>
    <div className="w-full max-w-md">
      <PopoverAnchor>
        <div className="h-status-bar rounded-row flex items-center justify-between border px-2">
          <span className="text-meta text-muted-foreground">On air 12:04</span>
          <PopoverTrigger render={<Button size="xs" variant="ghost" />}>
            <SpeakerOnIcon data-icon="inline-start" />
            Sounds
          </PopoverTrigger>
        </div>
      </PopoverAnchor>
    </div>
    <PopoverContent align="end" side="top">
      <div className="grid grid-cols-2 gap-1">
        {SOUNDS.map((sound) => (
          <Button key={sound} variant="ghost">
            {sound}
          </Button>
        ))}
      </div>
    </PopoverContent>
  </Popover>
);

export default PopoverAnchorExample;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `glass-float` | The popup tier: the window's solid tone, a 1 px rim and the float drop |
| `rounded-lg` | The popup tier's 10 px corners |
| `w-72`, `p-3`, `gap-3` | Its default width and spacing |
| `data-open`, `data-closed` | Fades and scales from 0.98 in 100 ms, with no slide |
| `data-side`, `data-align` | Where it opened |

## Keyboard

| Key              | Action                                              |
| ---------------- | --------------------------------------------------- |
| `Enter`, `Space` | On the trigger, opens or closes the popover         |
| `Tab`            | Moves through the popover's controls                |
| `Escape`         | Closes the popover and returns focus to the trigger |

## Accessibility

The popover is a dialog: `PopoverTitle` names it and `PopoverDescription` describes it. Focus moves into it on open and back to the trigger on close.

## API reference

Every [Base UI Popover](https://base-ui.com/react/components/popover) prop, plus:

### PopoverContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | — |
| `sideOffset` | `number` | `4` | — |
| `align` | `"start" \| "center" \| "end"` | `"center"` | — |
| `alignOffset` | `number` | `0` | — |
| `anchor` | `Element \| RefObject<Element> \| VirtualElement \| null` | — | What to position against. Defaults to the PopoverAnchor, then the trigger. |

### PopoverAnchor

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | — | Replaces the rendered <div>. |

# Progress (/docs/components/progress)

```tsx title="components/examples/progress-demo.tsx"
"use client";

import {
  Progress,
  ProgressLabel,
  ProgressValue,
} from "@/components/ui/progress";

const ProgressDemo = () => (
  <Progress className="max-w-xs" value={42}>
    <ProgressLabel>Uploading recording…</ProgressLabel>
    <ProgressValue />
  </Progress>
);

export default ProgressDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/progress
```

## Usage

```tsx
import {
  Progress,
  ProgressLabel,
  ProgressValue,
} from "@/components/ui/progress";
```

```tsx
<Progress aria-label="Update download" value={64} />
```

## Anatomy

`Progress` draws its own track and indicator after its children, so a label and a value sit above the bar.

```tsx
<Progress>
  <ProgressLabel />
  <ProgressValue />
</Progress>
```

## Examples

### Steps

`value` runs from 0 to `max` (100 by default), so count steps directly. `ProgressValue` takes a function to say the count in words.

```tsx title="components/examples/progress-steps.tsx"
"use client";

import { useState } from "react";

import { Button } from "@/components/ui/button";
import {
  Progress,
  ProgressLabel,
  ProgressValue,
} from "@/components/ui/progress";

const POSES = 8;

const ProgressSteps = () => {
  const [done, setDone] = useState(3);
  return (
    <div className="flex w-full max-w-xs flex-col items-start gap-3">
      <Progress max={POSES} value={done}>
        <ProgressLabel>Cutting out poses</ProgressLabel>
        <ProgressValue>
          {(_, value) => `${value ?? 0} of ${POSES}`}
        </ProgressValue>
      </Progress>
      <Button
        disabled={done === POSES}
        onClick={() => setDone((count) => Math.min(POSES, count + 1))}
        size="xs"
        variant="secondary"
      >
        Next pose
      </Button>
    </div>
  );
};

export default ProgressSteps;
```

### Inline

With no label of its own, give the bar an `aria-label` and set it beside the words that explain it, as Settings does for an update.

```tsx title="components/examples/progress-inline.tsx"
"use client";

import { Progress } from "@/components/ui/progress";

const ProgressInline = () => (
  <div className="flex w-full max-w-sm items-center justify-between gap-4">
    <div className="flex flex-col">
      <span className="text-sm font-medium">Videorc 2.4</span>
      <span className="text-muted-foreground text-xs">
        Downloading the update…
      </span>
    </div>
    <Progress
      aria-label="Update download"
      className="w-32 shrink-0"
      value={64}
    />
  </div>
);

export default ProgressInline;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `chrome-fill` | The indicator: the same polished chrome as the primary button |
| `bg-muted`, `rounded-full`, `h-1.5` | The 6 px round track |
| `duration-150 ease-out` | The indicator's width change |
| `data-progressing`, `data-complete` | On every part, from Base UI |

## Accessibility

Base UI renders a `progressbar` with `aria-valuenow`, `aria-valuemin` and `aria-valuemax`, and `aria-valuetext` as a percentage. `ProgressLabel` names the bar; without one, pass `aria-label`. A bar is never the only place a fact lives: put the number or the step in words beside it ("3 of 8", "Uploading recording…").

Progress is for work with a known end. For work without one, use a spinner and a pending label that ends in "…".

## API reference

### Progress

Every [Base UI Progress Root](https://base-ui.com/react/components/progress) prop, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number \| null` | — | From 0 to max. null is indeterminate. |
| `max` | `number` | `100` | A non-positive max (a total not known yet) reads as 100. |

### ProgressLabel, ProgressValue

Every [Base UI Progress Label and Value](https://base-ui.com/react/components/progress) prop. `ProgressValue` takes `(formattedValue, value) => ReactNode` as its child.

### ProgressTrack, ProgressIndicator

The parts `Progress` draws for you, exported for a custom layout.

# Scroll Area (/docs/components/scroll-area)

```tsx title="components/examples/scroll-area-demo.tsx"
"use client";

import { ScrollArea } from "@/components/ui/scroll-area";

const RECORDINGS = [
  { duration: "1:02:14", id: "r1", title: "Launch demo" },
  { duration: "48:30", id: "r2", title: "Weekly stream" },
  { duration: "12:05", id: "r3", title: "Podcast intro" },
  { duration: "2:31:40", id: "r4", title: "Speedrun practice" },
  { duration: "35:12", id: "r5", title: "Q&A with viewers" },
  { duration: "9:48", id: "r6", title: "Camera test" },
  { duration: "1:15:00", id: "r7", title: "Studio tour" },
  { duration: "22:19", id: "r8", title: "Sound check" },
  { duration: "54:03", id: "r9", title: "Charity stream" },
  { duration: "6:27", id: "r10", title: "Teaser clip" },
  { duration: "41:56", id: "r11", title: "Patch notes" },
  { duration: "18:44", id: "r12", title: "Interview" },
];

const ScrollAreaDemo = () => (
  <div className="rounded-row h-60 w-64 border">
    <ScrollArea className="h-full">
      <ul aria-label="Recordings" className="flex flex-col p-1">
        {RECORDINGS.map((recording) => (
          <li
            className="rounded-chip hover:bg-accent flex h-8 items-center justify-between gap-3 px-2 text-sm"
            key={recording.id}
          >
            <span className="truncate">{recording.title}</span>
            <span className="text-muted-foreground text-meta tabular-nums">
              {recording.duration}
            </span>
          </li>
        ))}
      </ul>
    </ScrollArea>
  </div>
);

export default ScrollAreaDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/scroll-area
```

## Usage

```tsx
import { ScrollArea } from "@/components/ui/scroll-area";
```

```tsx
<ScrollArea className="h-64">{recordings}</ScrollArea>
```

## Anatomy

```tsx
<ScrollArea>
  {children}
  <ScrollBar orientation="horizontal" />
</ScrollArea>
```

`ScrollArea` brings its own vertical `ScrollBar`. Add a horizontal one as a child when the content scrolls sideways.

## Examples

### Capped height

The root's height follows its content, so a cap goes on the viewport with `viewportClassName` (`max-h-56`). `type="hover"` also shows the thumb while the pointer is over the area, which suits a chat you read with the mouse on it.

```tsx title="components/examples/scroll-area-chat.tsx"
"use client";

import { ScrollArea } from "@/components/ui/scroll-area";

const MESSAGES = [
  { author: "maya_streams", id: "m1", text: "Hi from Lisbon!" },
  { author: "jonas", id: "m2", text: "The new overlay looks great." },
  { author: "priya.dev", id: "m3", text: "Is the audio a bit quiet?" },
  { author: "maya_streams", id: "m4", text: "Sounds fine here." },
  { author: "nightowl", id: "m5", text: "What camera is that?" },
  { author: "jonas", id: "m6", text: "Can you show the scene setup again?" },
  { author: "priya.dev", id: "m7", text: "Fixed now, thanks!" },
  { author: "nightowl", id: "m8", text: "First time here, hello." },
  { author: "kai", id: "m9", text: "Clip that!" },
  { author: "maya_streams", id: "m10", text: "See you next week." },
];

const ScrollAreaChat = () => (
  <div className="rounded-row w-72 border">
    <ScrollArea type="hover" viewportClassName="max-h-56">
      <ol aria-label="Chat messages" className="flex flex-col gap-2 p-3">
        {MESSAGES.map((message) => (
          <li className="text-sm" key={message.id}>
            <span className="text-muted-foreground font-medium">
              {message.author}
            </span>{" "}
            {message.text}
          </li>
        ))}
      </ol>
    </ScrollArea>
  </div>
);

export default ScrollAreaChat;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `--scrollbar-thumb`, `--scrollbar-thumb-hover` | The thumb and its hover fill; light mode's is darker to register on porcelain |
| `--scrollbar-thumb-ring` | The thumb's 1 px inset ring |
| `data-scrolling`, `data-hovering` | On the scrollbar while scrolling, and while the pointer is over the area |
| `data-type` | The `type`, on the root |

There is no track and no edge hairline: only the thumb reads.

## Keyboard

| Key | Action |
| --- | --- |
| <kbd>Tab</kbd> | Focuses the viewport when its content overflows |
| <kbd>↑</kbd> <kbd>↓</kbd> <kbd>←</kbd> <kbd>→</kbd> | Scroll a step |
| <kbd>Page Up</kbd> <kbd>Page Down</kbd> | Scroll a page |
| <kbd>Home</kbd> <kbd>End</kbd> | Scroll to the start or the end |

## Accessibility

The viewport is a native scroller, so wheel, trackpad and keyboard scrolling work as everywhere else. It takes focus only while its content overflows, and shows the focus ring then. Name the list inside it (`aria-label="Chat messages"`), not the scroll area.

## API reference

### ScrollArea

Every [Base UI Scroll Area](https://base-ui.com/react/components/scroll-area) Root prop, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `"scroll" \| "hover" \| "auto" \| "always"` | `"scroll"` | When the thumb shows: while scrolling, also on hover, whenever the content overflows, or always. |
| `viewportClassName` | `string` | — | Classes for the element that scrolls, such as a max-h cap. |

### ScrollBar

Every Base UI Scroll Area Scrollbar prop. `orientation` is `"vertical"` by default.

# Segmented Control (/docs/components/segmented-control)

```tsx title="components/examples/segmented-control-demo.tsx"
"use client";

import { useState } from "react";

import { SegmentedControl } from "@/components/ui/segmented-control";

type Theme = "light" | "dark" | "system";

const THEMES = [
  { label: "Light", value: "light" },
  { label: "Dark", value: "dark" },
  { label: "System", value: "system" },
] as const;

const SegmentedControlDemo = () => {
  const [theme, setTheme] = useState<Theme>("system");
  return (
    <SegmentedControl
      aria-label="Theme"
      onValueChange={setTheme}
      options={THEMES}
      value={theme}
    />
  );
};

export default SegmentedControlDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/segmented-control
```

## Usage

```tsx
import { SegmentedControl } from "@/components/ui/segmented-control";
```

```tsx
<SegmentedControl
  aria-label="Theme"
  onValueChange={setTheme}
  options={[
    { label: "Light", value: "light" },
    { label: "Dark", value: "dark" },
    { label: "System", value: "system" },
  ]}
  value={theme}
/>
```

Which control when:

- **Segmented control** chooses a value: theme, fit, corner, kind of cut.
- [Tabs](/docs/components/tabs) switch a view, a page or a pane with its own content.
- [Toggle group](/docs/components/toggle-group) is for filter chips: several on at once, or a filter row.
- A [Switch](/docs/components/switch) is for a boolean, and a one-shot action is a [Button](/docs/components/button).

## Examples

### Sizes

`size="sm"` (20 px segments) fits a toolbar or a small window. `activationMode="manual"` makes the arrow keys only move focus, and Space or Enter choose: use it when a change is heavy, such as switching a live scene.

```tsx title="components/examples/segmented-control-sizes.tsx"
"use client";

import { useState } from "react";

import { SegmentedControl } from "@/components/ui/segmented-control";

type Fit = "fit" | "fill";
type TextSize = "sm" | "md" | "lg";

const FITS = [
  { label: "Fit", value: "fit" },
  { label: "Fill", value: "fill" },
] as const;

const TEXT_SIZES = [
  { "aria-label": "Small text", label: "Small", value: "sm" },
  { "aria-label": "Medium text", label: "Medium", value: "md" },
  { "aria-label": "Large text", label: "Large", value: "lg" },
] as const;

const SegmentedControlSizes = () => {
  const [fit, setFit] = useState<Fit>("fit");
  const [textSize, setTextSize] = useState<TextSize>("md");
  return (
    <div className="flex flex-col items-center gap-4">
      <SegmentedControl
        aria-label="Camera fit"
        onValueChange={setFit}
        options={FITS}
        value={fit}
      />
      <SegmentedControl
        activationMode="manual"
        aria-label="Text size"
        onValueChange={setTextSize}
        options={TEXT_SIZES}
        size="sm"
        value={textSize}
      />
    </div>
  );
};

export default SegmentedControlSizes;
```

### Disabled with a reason

A disabled control always says why. Pass `disabledReason` with `disabled` and the reason shows as a line under the control and describes the group.

```tsx title="components/examples/segmented-control-disabled.tsx"
"use client";

import { SegmentedControl } from "@/components/ui/segmented-control";

const ORIENTATIONS = [
  { label: "Horizontal", value: "horizontal" },
  { label: "Vertical", value: "vertical" },
] as const;

const SegmentedControlDisabled = () => (
  <SegmentedControl
    aria-label="Studio orientation"
    disabled
    disabledReason="Locked while you’re recording or live. Stop to switch orientation."
    onValueChange={() => null}
    options={ORIENTATIONS}
    value="horizontal"
  />
);

export default SegmentedControlDisabled;
```

### Icons

Draw an option as an icon with an `aria-label`, and give it a `tooltip`: its name on hover and on focus, never a native `title`.

```tsx title="components/examples/segmented-control-icons.tsx"
"use client";

import { useState } from "react";

import { DesktopIcon, MobileIcon } from "@/components/icons";
import { SegmentedControl } from "@/components/ui/segmented-control";

type Orientation = "horizontal" | "vertical";

const ORIENTATIONS = [
  {
    "aria-label": "Horizontal",
    label: <DesktopIcon />,
    tooltip: "Horizontal · 16:9",
    value: "horizontal",
  },
  {
    "aria-label": "Vertical",
    label: <MobileIcon />,
    tooltip: "Vertical · 9:16",
    value: "vertical",
  },
] as const;

const SegmentedControlIcons = () => {
  const [orientation, setOrientation] = useState<Orientation>("horizontal");
  return (
    <SegmentedControl
      aria-label="Studio orientation"
      onValueChange={setOrientation}
      options={ORIENTATIONS}
      value={orientation}
    />
  );
};

export default SegmentedControlIcons;
```

## Theming

Segmented control wears the same track and segment as [Tabs](/docs/components/tabs). Both read it from `tabs-variants`, a small module with no Base UI import, so a segmented control costs a window's first bundle nothing:

- `tabsListVariants({ variant })` is the track.
- `tabsTriggerBaseClassName` is one segment, before its selected state.

| Token or attribute | Meaning |
| --- | --- |
| `bg-foreground/5`, `ring-border` | The recessed track |
| `chrome-plate` | The checked segment, keyed off `aria-checked` |
| `rounded-row`, `rounded-chip` | The track and a segment |
| `min-h-control`, `min-h-6` | The `default` and `sm` track heights |
| `data-checked`, `data-unchecked` | On every segment, as a Base UI radio marks it |
| `data-size` | On the track: `default` or `sm` |

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Lands on the checked option, or the first enabled one; `Tab` again leaves the group |
| `ArrowRight`, `ArrowDown` | Moves to the next enabled option, wrapping; checks it unless activation is manual |
| `ArrowLeft`, `ArrowUp` | Moves to the previous enabled option, wrapping; checks it unless activation is manual |
| `Home`, `End` | Moves to the first or last enabled option |
| `Space`, `Enter` | Checks the focused option |

## Accessibility

It follows the WAI-ARIA radio group pattern: the track is a `radiogroup` and each option a `radio` with `aria-checked`. Name it with `aria-label`, or put it in a [Field](/docs/components/field): the Field's label names the group through `aria-labelledby` unless the group carries its own `aria-label`. While disabled with a reason, the group is `aria-disabled` and `aria-describedby` the reason, so a screen reader hears why.

`onValueChange` fires only with a newly checked value. An option's own `onClick` still runs on the checked option: the hook for choosing it again (replay, re-apply).

## API reference

Every `div` prop, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` | `SegmentedControlOption<T>[]` | — | The options, in order. Each also takes any button prop and data-* attributes. |
| `value` | `T \| null \| undefined` | — | The checked option. A value not offered checks none. |
| `onValueChange` | `(value: T) => void` | — | Called with a newly checked value, never with the one already checked. |
| `disabled` | `boolean` | `false` | — |
| `disabledReason` | `string \| null` | — | Why the control is disabled: shown under it while disabled. |
| `activationMode` | `"automatic" \| "manual"` | `"automatic"` | — |
| `size` | `"default" \| "sm"` | `"default"` | — |

### SegmentedControlOption

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `T` | — | — |
| `label` | `ReactNode` | — | Text, or an icon with an aria-label. |
| `disabled` | `boolean` | `false` | — |
| `tooltip` | `ReactNode` | — | The option's name on hover and focus, for an icon option. |

`segmentedTargetIndex(enabled, current, key)` and `segmentedTabStop(enabled, checkedIndex)` are the keyboard rules as pure functions, for a control that needs the same roving focus.

# Select (/docs/components/select)

```tsx title="components/examples/select-demo.tsx"
"use client";

import { Field, FieldLabel } from "@/components/ui/field";
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select";

const FRAME_RATES = [
  { label: "24 fps", value: "24" },
  { label: "30 fps", value: "30" },
  { label: "60 fps", value: "60" },
];

const SelectDemo = () => (
  <Field className="w-48">
    <FieldLabel>Frame rate</FieldLabel>
    <Select defaultValue="60" items={FRAME_RATES}>
      <SelectTrigger className="w-full">
        <SelectValue />
      </SelectTrigger>
      <SelectContent>
        <SelectGroup>
          {FRAME_RATES.map((rate) => (
            <SelectItem key={rate.value} value={rate.value}>
              {rate.label}
            </SelectItem>
          ))}
        </SelectGroup>
      </SelectContent>
    </Select>
  </Field>
);

export default SelectDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/select
```

## Usage

```tsx
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select";
```

```tsx
const frameRates = [
  { label: "30 fps", value: "30" },
  { label: "60 fps", value: "60" },
];

<Select defaultValue="60" items={frameRates}>
  <SelectTrigger aria-label="Frame rate">
    <SelectValue />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      {frameRates.map((rate) => (
        <SelectItem key={rate.value} value={rate.value}>
          {rate.label}
        </SelectItem>
      ))}
    </SelectGroup>
  </SelectContent>
</Select>;
```

Pass `items` to the root so the trigger shows the chosen item's label rather than its raw value. Put items in a `SelectGroup`: the group brings the 4 px inset the items sit in.

## Anatomy

```tsx
<Select>
  <SelectTrigger>
    <SelectValue />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      <SelectLabel />
      <SelectItem />
    </SelectGroup>
    <SelectSeparator />
  </SelectContent>
</Select>
```

## Examples

### Placeholder

The placeholder is an item with a `null` value in `items`. Leave it out of the list when it can't be chosen back.

```tsx title="components/examples/select-placeholder.tsx"
"use client";

import { Field, FieldLabel } from "@/components/ui/field";
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select";

// The null item is the placeholder: the trigger shows its label until a
// destination is chosen. It isn't in the list, so it can't be chosen back.
const DESTINATIONS = [
  { label: "Choose a destination", value: null },
  { label: "YouTube", value: "youtube" },
  { label: "Twitch", value: "twitch" },
  { label: "Kick", value: "kick" },
];

const SelectPlaceholder = () => (
  <Field className="w-56">
    <FieldLabel>Stream to</FieldLabel>
    <Select items={DESTINATIONS}>
      <SelectTrigger className="w-full">
        <SelectValue />
      </SelectTrigger>
      <SelectContent>
        <SelectGroup>
          {DESTINATIONS.filter((entry) => entry.value !== null).map((entry) => (
            <SelectItem key={entry.value} value={entry.value}>
              {entry.label}
            </SelectItem>
          ))}
        </SelectGroup>
      </SelectContent>
    </Select>
  </Field>
);

export default SelectPlaceholder;
```

### Groups

Label groups of like things with `SelectLabel`, and split them with a `SelectSeparator` inside the next group. With `alignItemWithTrigger={false}` the list opens under the trigger instead of over it.

```tsx title="components/examples/select-groups.tsx"
"use client";

import { Field, FieldLabel } from "@/components/ui/field";
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectLabel,
  SelectSeparator,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select";

const SOURCES = [
  {
    items: [
      { label: "Built-in Retina display", value: "display-built-in" },
      { label: "Studio Display", value: "display-studio" },
    ],
    label: "Displays",
  },
  {
    items: [
      { label: "Keynote", value: "window-keynote" },
      { label: "Safari", value: "window-safari" },
    ],
    label: "Windows",
  },
];

const ITEMS = SOURCES.flatMap((group) => group.items);

const SelectGroups = () => (
  <Field className="w-60">
    <FieldLabel>Screen</FieldLabel>
    <Select defaultValue="display-built-in" items={ITEMS}>
      <SelectTrigger className="w-full">
        <SelectValue />
      </SelectTrigger>
      <SelectContent alignItemWithTrigger={false}>
        {SOURCES.map((group, index) => (
          <SelectGroup key={group.label}>
            {index > 0 ? <SelectSeparator /> : null}
            <SelectLabel>{group.label}</SelectLabel>
            {group.items.map((item) => (
              <SelectItem key={item.value} value={item.value}>
                {item.label}
              </SelectItem>
            ))}
          </SelectGroup>
        ))}
      </SelectContent>
    </Select>
  </Field>
);

export default SelectGroups;
```

### Sizes

`xs` (24 px) is for dense rows only: a row's trailing control, a card's actions, the Stream Manager's panes. A page's or a dialog's selects stay 28 px.

```tsx title="components/examples/select-sizes.tsx"
"use client";

import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select";

const LAYOUTS = [
  { label: "Camera only", value: "camera" },
  { label: "Screen and camera", value: "screen-camera" },
  { label: "Screen only", value: "screen" },
];

const LayoutSelect = ({ size }: { size: "default" | "xs" }) => (
  <Select defaultValue="screen-camera" items={LAYOUTS}>
    <SelectTrigger aria-label="Layout" size={size}>
      <SelectValue />
    </SelectTrigger>
    <SelectContent>
      <SelectGroup>
        {LAYOUTS.map((layout) => (
          <SelectItem key={layout.value} value={layout.value}>
            {layout.label}
          </SelectItem>
        ))}
      </SelectGroup>
    </SelectContent>
  </Select>
);

const SelectSizes = () => (
  <div className="flex flex-wrap items-center gap-2">
    <LayoutSelect size="default" />
    <LayoutSelect size="xs" />
  </div>
);

export default SelectSizes;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `bg-input/50`, `rounded-chip` | The trigger's fill and 6 px corners |
| `h-control` | The 28 px trigger, by `data-size="default"`; `xs` is 24 px |
| `data-placeholder` | On the trigger while nothing is chosen: muted text |
| `glass-float`, `rounded-lg` | The popup tier and its 10 px corners |
| `min-h-7`, `rounded-chip` | 28 px items with 6 px corners |
| `data-align-trigger` | The list opens over the trigger, unanimated |
| `overscroll-contain` | A long list's scroll doesn't chain to the page |

`selectTriggerClassName` is the trigger's look on its own, for a button that opens a popover but must look exactly like a select.

## Keyboard

| Key | Action |
| --- | --- |
| `Enter`, `Space`, `ArrowDown`, `ArrowUp` | On the trigger, opens the list |
| `ArrowDown`, `ArrowUp` | Moves between items |
| `Home`, `End` | Moves to the first or last item |
| A letter | Moves to the next item that starts with it |
| `Enter`, `Space` | Chooses the highlighted item |
| `Escape` | Closes the list without choosing |

## Accessibility

Every trigger has a name. Inside a [Field](/docs/components/field) the `FieldLabel` names it and the `FieldDescription` describes it, with no ids to wire; outside one, give the trigger an `aria-label`. The list stops wheel events at its edge, so a fader or a scrolling pane behind it doesn't move.

## API reference

Every [Base UI Select](https://base-ui.com/react/components/select) prop, plus:

### SelectTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"default" \| "xs"` | `"default"` | — |

### SelectContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `alignItemWithTrigger` | `boolean` | `true` | Opens over the trigger with the chosen item on its value. False opens it below. |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | — |
| `sideOffset` | `number` | `4` | — |
| `align` | `"start" \| "center" \| "end"` | `"center"` | — |
| `alignOffset` | `number` | `0` | — |

# Separator (/docs/components/separator)

```tsx title="components/examples/separator-demo.tsx"
"use client";

import { Separator } from "@/components/ui/separator";

const SeparatorDemo = () => (
  <div className="w-full max-w-xs text-sm">
    <p className="font-medium">Livestream</p>
    <p className="text-muted-foreground">
      Go live to YouTube, Twitch and X at once.
    </p>
    <Separator className="my-3" />
    <div className="flex h-5 items-center gap-3">
      <span>Studio</span>
      <Separator orientation="vertical" />
      <span>Sources</span>
      <Separator orientation="vertical" />
      <span>Library</span>
    </div>
  </div>
);

export default SeparatorDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/separator
```

## Usage

```tsx
import { Separator } from "@/components/ui/separator";
```

```tsx
<Separator orientation="vertical" />
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `bg-border` | The hairline colour, never more than 1 px |
| `data-orientation` | `horizontal` or `vertical`; a vertical one stretches to its row |

## Accessibility

A separator is `role="separator"` with its `aria-orientation`, so a screen reader hears where one group ends. When a line is only decoration, draw a `border-border` hairline on the element instead.

## API reference

Every [Base UI Separator](https://base-ui.com/react/components/separator) prop.

# Shortcut Keys (/docs/components/shortcut-keys)

```tsx title="components/examples/shortcut-keys-demo.tsx"
"use client";

import { ShortcutKeys } from "@/components/ui/shortcut-keys";

const SHORTCUTS = [
  { accelerator: "CmdOrCtrl+K", label: "Search" },
  { accelerator: "CmdOrCtrl+P", label: "Open Preview" },
  { accelerator: "CmdOrCtrl+Shift+J", label: "Open Stream Manager" },
  { accelerator: "Space", label: "Start or stop recording" },
];

const ShortcutKeysDemo = () => (
  <ul className="flex w-full max-w-xs flex-col gap-2 text-sm">
    {SHORTCUTS.map((shortcut) => (
      <li
        className="flex items-center justify-between gap-4"
        key={shortcut.label}
      >
        {shortcut.label}
        <ShortcutKeys accelerator={shortcut.accelerator} />
      </li>
    ))}
  </ul>
);

export default ShortcutKeysDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/shortcut-keys
```

## Usage

```tsx
import { ShortcutKeys } from "@/components/ui/shortcut-keys";
```

```tsx
<ShortcutKeys accelerator="CmdOrCtrl+Shift+J" />
```

Author a shortcut once, as the accelerator Electron binds (`CmdOrCtrl+Shift+J`, `Enter`, `Space`), and print it only through ShortcutKeys. An unbound shortcut (an empty accelerator) renders nothing.

## Examples

### Per platform

macOS reads as one keycap in system order with its own glyphs (⇧⌘J, ⌘↵, ⌫). Windows and Linux read as words joined by "+" (Ctrl+Shift+J, Ctrl+Enter, Backspace). Pass `platform` when the app knows it; Electron's `process.platform` is the value.

```tsx title="components/examples/shortcut-keys-platforms.tsx"
"use client";

import { ShortcutKeys } from "@/components/ui/shortcut-keys";

const ACCELERATORS = [
  "CmdOrCtrl+Shift+J",
  "CmdOrCtrl+Enter",
  "Shift+Backspace",
  "CmdOrCtrl+,",
];

const ShortcutKeysPlatforms = () => (
  <table className="text-sm">
    <thead className="text-muted-foreground text-xs">
      <tr>
        <th className="pr-6 pb-2 text-left font-medium">Accelerator</th>
        <th className="pr-6 pb-2 text-left font-medium">macOS</th>
        <th className="pb-2 text-left font-medium">Windows</th>
      </tr>
    </thead>
    <tbody>
      {ACCELERATORS.map((accelerator) => (
        <tr key={accelerator}>
          <td className="text-muted-foreground py-1 pr-6 font-mono text-xs">
            {accelerator}
          </td>
          <td className="py-1 pr-6">
            <ShortcutKeys accelerator={accelerator} platform="darwin" />
          </td>
          <td className="py-1">
            <ShortcutKeys accelerator={accelerator} platform="win32" />
          </td>
        </tr>
      ))}
    </tbody>
  </table>
);

export default ShortcutKeysPlatforms;
```

### Text

`variant="text"` is the status bar's quiet hint: the same label with no keycap.

```tsx title="components/examples/shortcut-keys-text.tsx"
"use client";

import { ShortcutKeys } from "@/components/ui/shortcut-keys";

const ShortcutKeysText = () => (
  <div className="h-status-bar text-muted-foreground flex w-full max-w-sm items-center justify-between border-t px-3 text-xs">
    <span>Ready to record</span>
    <span className="flex items-center gap-1.5">
      Search
      <ShortcutKeys accelerator="CmdOrCtrl+K" variant="text" />
    </span>
  </div>
);

export default ShortcutKeysText;
```

## Theming

| Token or attribute | Meaning                                                 |
| ------------------ | ------------------------------------------------------- |
| `glass-keycap`     | The `chip` variant, through [Kbd](/docs/components/kbd) |
| `data-accelerator` | The accelerator it prints, on either variant            |
| `data-slot`        | `kbd` for the chip, `shortcut-keys` for the text        |

## Accessibility

The label is plain text inside a `<kbd>` or a `<span>`. Tell assistive tech about the shortcut on the control it triggers, with `aria-keyshortcuts={shortcutAriaKeys(accelerator)}` from `@/lib/platform` (Meta+K on macOS, Control+K elsewhere).

Without `platform`, ShortcutKeys reads `data-platform` on `<html>` (set it before the first paint), then the user agent, so a Mac never flashes "Ctrl" in a window that renders on the client. A server can't know the reader's platform: server-rendered markup prints the Windows spelling, and the client corrects it as it hydrates.

## API reference

Every `kbd` prop except `children`, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `accelerator` | `string` | — | An Electron accelerator: CmdOrCtrl+Shift+J, Enter, Space. |
| `platform` | `string` | — | darwin, win32, linux… Defaults to data-platform on <html>, then the user agent. |
| `variant` | `"chip" \| "text"` | `"chip"` | — |

For running copy and titles, `shortcutLabel(accelerator, platform?)` from `@/lib/platform` returns the same label as a string.

# Shortcut Tooltip (/docs/components/shortcut-tooltip)

```tsx title="components/examples/shortcut-tooltip-demo.tsx"
"use client";

import { MicrophoneIcon, PreviewIcon, SearchIcon } from "@/components/icons";
import { Button } from "@/components/ui/button";
import { ShortcutTooltip } from "@/components/ui/shortcut-tooltip";

const ShortcutTooltipDemo = () => (
  <div className="flex items-center gap-1">
    <ShortcutTooltip accelerator="CmdOrCtrl+K" label="Search">
      <Button aria-label="Search" size="icon" variant="ghost">
        <SearchIcon />
      </Button>
    </ShortcutTooltip>
    <ShortcutTooltip accelerator="CmdOrCtrl+P" label="Open Preview">
      <Button aria-label="Open Preview" size="icon" variant="ghost">
        <PreviewIcon />
      </Button>
    </ShortcutTooltip>
    <ShortcutTooltip label="Mute microphone">
      <Button aria-label="Mute microphone" size="icon" variant="ghost">
        <MicrophoneIcon />
      </Button>
    </ShortcutTooltip>
  </div>
);

export default ShortcutTooltipDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/shortcut-tooltip
```

## Usage

```tsx
import { ShortcutTooltip } from "@/components/ui/shortcut-tooltip";
```

```tsx
<ShortcutTooltip accelerator="CmdOrCtrl+K" label="Search">
  <Button aria-label="Search" size="icon" variant="ghost">
    <SearchIcon />
  </Button>
</ShortcutTooltip>
```

With no `accelerator` (nothing bound yet) the tooltip shows the label alone.

## Examples

### Around a switch

The trigger is a wrapping `<span>`, so the tooltip's handlers and its `data-popup-open` land there: a Switch keeps its own `data-checked`, and a Button its own `render`. `className` lays the wrapper out (`flex flex-col` around a whole row); it never styles the control.

```tsx title="components/examples/shortcut-tooltip-switch.tsx"
"use client";

import { useState } from "react";

import { ShortcutTooltip } from "@/components/ui/shortcut-tooltip";
import { Switch } from "@/components/ui/switch";

const ShortcutTooltipSwitch = () => {
  const [live, setLive] = useState(true);
  return (
    <div className="flex items-center gap-2 text-sm">
      <ShortcutTooltip
        accelerator="CmdOrCtrl+Shift+M"
        label={live ? "Mute microphone" : "Unmute microphone"}
      >
        <Switch
          aria-label="Microphone"
          checked={live}
          onCheckedChange={setLive}
        />
      </ShortcutTooltip>
      <span aria-hidden>Microphone</span>
    </div>
  );
};

export default ShortcutTooltipSwitch;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `glass-float-tooltip` | The tooltip, through [Tooltip](/docs/components/tooltip) |
| `glass-keycap` | The shortcut, through [Shortcut keys](/docs/components/shortcut-keys) |
| `data-slot="tooltip-trigger"` | On the wrapper |

## Accessibility

The tooltip opens on hover and on keyboard focus of the control inside the wrapper. It names the control for sighted users only, so an icon-only control still needs its own `aria-label`, and a tooltip is never the only place a fact lives. Give the control `aria-keyshortcuts` when its shortcut matters to assistive tech.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | — | What the control does. |
| `accelerator` | `string` | — | The bound shortcut as an Electron accelerator; empty or absent when none is bound. |
| `platform` | `string` | — | Passed to Shortcut keys. |
| `className` | `string` | — | Layout for the wrapper, never styling. |
| `children` | `ReactElement` | — | The control. |

# Skeleton (/docs/components/skeleton)

```tsx title="components/examples/skeleton-demo.tsx"
"use client";

import { Skeleton } from "@/components/ui/skeleton";

const SkeletonDemo = () => (
  <div className="flex items-center gap-3">
    <Skeleton className="aspect-video w-32" />
    <div className="flex flex-col gap-2">
      <Skeleton className="h-4 w-44" />
      <Skeleton className="h-3 w-24" />
    </div>
  </div>
);

export default SkeletonDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/skeleton
```

## Usage

```tsx
import { Skeleton } from "@/components/ui/skeleton";
```

```tsx
<Skeleton className="h-4 w-44" />
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `bg-muted` | The placeholder fill |
| `rounded-row` | The 8 px row radius; pass `rounded-full` for a round picture |
| `animate-pulse` | The pulse, which reduced motion stops |

## Accessibility

A skeleton is decoration. Announce the loading once, on the region it fills (`aria-busy`), or with a [Spinner](/docs/components/spinner).

# Slider (/docs/components/slider)

```tsx title="components/examples/slider-demo.tsx"
"use client";

import { Field, FieldLabel } from "@/components/ui/field";
import { Slider } from "@/components/ui/slider";

const SliderDemo = () => (
  <Field className="max-w-sm">
    <FieldLabel>Buddy motion</FieldLabel>
    <Slider defaultValue={45} />
  </Field>
);

export default SliderDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/slider
```

## Usage

```tsx
import { Slider } from "@/components/ui/slider";
```

```tsx
<Slider aria-label="Microphone gain" defaultValue={60} />
```

One thumb takes a number; a range takes an array, and `onValueChange` hands back the same shape.

## Examples

### Value readout

Show the value beside the label, and pass the same words as `aria-valuetext` so a screen reader says "+6.0 dB", not "6".

```tsx title="components/examples/slider-readout.tsx"
"use client";

import { useState } from "react";

import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";
import { Slider } from "@/components/ui/slider";

const formatGain = (decibels: number) =>
  `${decibels > 0 ? "+" : ""}${decibels.toFixed(1)} dB`;

const SliderReadout = () => {
  const [gain, setGain] = useState(6);
  return (
    <Field className="max-w-sm">
      <div className="flex items-baseline justify-between gap-2">
        <FieldLabel>Microphone gain</FieldLabel>
        <output
          aria-hidden
          className="text-meta text-muted-foreground tabular-nums"
        >
          {formatGain(gain)}
        </output>
      </div>
      <Slider
        aria-valuetext={formatGain(gain)}
        max={20}
        min={-20}
        onValueChange={(value) => setGain(value)}
        step={0.5}
        value={gain}
      />
      <FieldDescription>
        Raise it until your voice peaks just under the red.
      </FieldDescription>
    </Field>
  );
};

export default SliderReadout;
```

### Range

Pass two values for two thumbs. `minStepsBetweenValues` keeps them apart, and `format` turns each thumb's spoken value into a unit.

```tsx title="components/examples/slider-range.tsx"
"use client";

import { Slider } from "@/components/ui/slider";

const SliderRange = () => (
  <Slider
    aria-label="Clip"
    className="max-w-sm"
    defaultValue={[12, 48]}
    format={{ style: "unit", unit: "second" }}
    max={60}
    minStepsBetweenValues={5}
  />
);

export default SliderRange;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `chrome-fill` | The range |
| `bg-foreground/15` | The 4 px track |
| `chrome-bead` | Every thumb |
| `ring-knob-ring` | The thumb's hairline rim; a 4 px ring on hover and focus |
| `data-orientation` | `horizontal` or `vertical` |
| `data-disabled` | Dims to 50% |
| `data-slot` | `slider`, `slider-track`, `slider-range`, `slider-thumb` |

## Keyboard

| Key | Action |
| --- | --- |
| <kbd>←</kbd> <kbd>→</kbd> <kbd>↑</kbd> <kbd>↓</kbd> | Moves the focused thumb one `step` |
| <kbd>Shift</kbd> with an arrow | Moves it one `largeStep` |
| <kbd>Page Up</kbd> <kbd>Page Down</kbd> | Moves it one `largeStep` |
| <kbd>Home</kbd> <kbd>End</kbd> | Moves it to the minimum or maximum |
| <kbd>Tab</kbd> | Moves to the next thumb, then the next control |

## Accessibility

Each thumb holds a native range input with `role="slider"`, and that is what a screen reader reads. So `aria-label`, `aria-labelledby`, `aria-describedby` and `aria-valuetext` go to every thumb, never the root. Inside a [Field](/docs/components/field), a slider that names nothing takes the `FieldLabel` through `aria-labelledby` (a label element can't point at a thumb) and the Field's descriptions. Outside a Field, always name it.

## API reference

Every [Base UI Slider](https://base-ui.com/react/components/slider) root prop, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number \| number[]` | — | The controlled value: a number for one thumb, an array for a range. |
| `defaultValue` | `number \| number[]` | `min` | The uncontrolled starting value. |
| `onValueChange` | `(value, eventDetails) => void` | — | Called while the value changes, with the same shape as value. |
| `onValueCommitted` | `(value, eventDetails) => void` | — | Called once a drag or a key press ends. |
| `min` | `number` | `0` | — |
| `max` | `number` | `100` | — |
| `aria-label` | `string` | — | Names every thumb. Inside a Field it replaces the FieldLabel. |
| `aria-labelledby` | `string` | — | Names every thumb. |
| `aria-describedby` | `string` | — | Describes every thumb. |
| `aria-valuetext` | `string` | — | The spoken value of every thumb. For a range, use format instead. |
| `thumbAlignment` | `"center" \| "edge" \| "edge-client-only"` | `"edge"` | Keeps the thumbs inside the track at either end. |

# Sonner (/docs/components/sonner)

```tsx title="components/examples/sonner-demo.tsx"
"use client";

import { toast } from "sonner";

import { Button } from "@/components/ui/button";

// A toast with a description stays at least 8 s, long enough to read it.
const TOAST_WITH_DESCRIPTION_MS = 8000;

const SonnerDemo = () => (
  <Button
    onClick={() =>
      toast.success("Recording saved", {
        description: "Just chatting, 1:12:04, is in your Library.",
        duration: TOAST_WITH_DESCRIPTION_MS,
      })
    }
    variant="secondary"
  >
    Save local recording
  </Button>
);

export default SonnerDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/sonner
```

## Usage

```tsx
import { Toaster } from "@/components/ui/sonner";
```

```tsx
<Toaster />
```

Mount one `Toaster` per window, then call `toast()` from `sonner` anywhere:

```tsx
import { toast } from "sonner";

toast.success("Recording saved");
```

Toasts are for news the interface doesn't already show: never for a routine change the user just watched happen, such as a scene, layout or source switch. When in doubt, don't toast. Give each kind of toast one `id`, so a newer one replaces the older and the same news never stacks.

## Examples

### Types

The type is the meaning, and it colours the icon only. Error: it failed and needs you. Warning: it can't happen now, or it's degraded. Info: neutral news, or a step to take in the browser. Success: work that finished out of view. Loading shows the spinner until the same `id` settles it.

```tsx title="components/examples/sonner-types.tsx"
"use client";

import { toast } from "sonner";

import { Button } from "@/components/ui/button";

const SAVE_TAKES_MS = 2000;

// One id per kind of toast: the saved toast replaces the pending one.
const saveRecording = () => {
  toast.loading("Saving recording…", { id: "recording-save" });
  setTimeout(() => {
    toast.success("Recording saved", { id: "recording-save" });
  }, SAVE_TAKES_MS);
};

const SonnerTypes = () => (
  <div className="flex flex-wrap items-center gap-2">
    <Button
      onClick={() => toast.success("Import complete")}
      variant="secondary"
    >
      Success
    </Button>
    <Button
      onClick={() => toast.info("Finish connecting YouTube in your browser")}
      variant="secondary"
    >
      Info
    </Button>
    <Button
      onClick={() =>
        toast.warning(
          "Renaming takeovers is locked while you're recording or live"
        )
      }
      variant="secondary"
    >
      Warning
    </Button>
    <Button
      onClick={() =>
        toast.error("Couldn't connect to Twitch", {
          description: "Check your connection, then try again.",
        })
      }
      variant="secondary"
    >
      Error
    </Button>
    <Button onClick={saveRecording} variant="secondary">
      Loading
    </Button>
  </div>
);

export default SonnerTypes;
```

### Undo

For a frequent action that is cheap to restore, act at once and offer Undo instead of asking first. A toast with an action stays until it's acted on or closed.

```tsx title="components/examples/sonner-undo.tsx"
"use client";

import { toast } from "sonner";

import { Button } from "@/components/ui/button";

const SonnerUndo = () => (
  <Button
    onClick={() =>
      toast("Message removed", {
        action: {
          label: "Undo",
          onClick: () => toast("Message restored"),
        },
        duration: Number.POSITIVE_INFINITY,
        id: "chat-removal",
      })
    }
    variant="secondary"
  >
    Remove message
  </Button>
);

export default SonnerUndo;
```

## Theming

The look lives in the theme's sonner block, not in the component: sonner injects unlayered CSS that a layered utility can't beat.

| Token or attribute | Meaning |
| --- | --- |
| `glass-float` | Every toast, whatever its type |
| `data-type` | `success`, `info`, `warning` or `error`: sets `tone-*` for the icon |
| `--chip-tone` | The icon's colour; the panel, its rim and the text stay neutral |

## Keyboard

| Key              | Action                                          |
| ---------------- | ----------------------------------------------- |
| `Alt+T`          | Moves focus to the toasts                       |
| `Tab`            | Moves between a toast's action and close button |
| `Enter`, `Space` | Presses the focused button                      |

## Accessibility

Toasts are announced from a live region labelled "Notifications". Each one has a close button labelled "Dismiss notification", and the toasts wait while the pointer is over them.

## API reference

Every [sonner Toaster](https://sonner.emilkowal.ski/toaster) prop, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeButton` | `boolean` | `true` | Every toast can be dismissed. |
| `toastOptions.closeButtonAriaLabel` | `string` | `"Dismiss notification"` | — |
| `theme` | `"light" \| "dark" \| "system"` | — | Follows next-themes unless set. |

# Spinner (/docs/components/spinner)

```tsx title="components/examples/spinner-demo.tsx"
"use client";

import { Spinner } from "@/components/ui/spinner";

const SpinnerDemo = () => (
  <div className="flex items-center gap-4">
    <Spinner aria-label="Loading scenes" />
    <Spinner aria-label="Loading sources" className="size-6" />
  </div>
);

export default SpinnerDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/spinner
```

## Usage

```tsx
import { Spinner } from "@/components/ui/spinner";
```

```tsx
<Spinner aria-label="Loading scenes" />
```

## Examples

### In a button

Beside a pending label ("Saving…") the spinner is decoration: pass `aria-hidden` and mark it `data-icon="inline-start"` so the button adjusts its padding.

```tsx title="components/examples/spinner-button.tsx"
"use client";

import { useEffect, useState } from "react";

import { Button } from "@/components/ui/button";
import { Spinner } from "@/components/ui/spinner";

const SAVE_MS = 1500;

const SpinnerButton = () => {
  const [saving, setSaving] = useState(false);

  useEffect(() => {
    if (!saving) {
      return;
    }
    const timer = setTimeout(() => setSaving(false), SAVE_MS);
    return () => clearTimeout(timer);
  }, [saving]);

  return (
    <Button disabled={saving} onClick={() => setSaving(true)}>
      {saving ? <Spinner aria-hidden data-icon="inline-start" /> : null}
      {saving ? "Saving…" : "Save recording"}
    </Button>
  );
};

export default SpinnerButton;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `animate-spin` | The turn, which reduced motion stops |
| `size-*` | Sets a size; without one it takes its slot's icon size, or 1em |

## Accessibility

On its own the spinner is `role="status"`, named "Loading" or its `aria-label`. With `aria-hidden` it drops the role and the name, for a spinner beside its own words or inside a region that already announces the wait.

## API reference

Every icon prop (`AppIconProps`), plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` | `"Loading"` | What is loading. |
| `aria-hidden` | `boolean` | — | Silences it beside its own words. |

# Switch (/docs/components/switch)

```tsx title="components/examples/switch-demo.tsx"
"use client";

import {
  Field,
  FieldContent,
  FieldDescription,
  FieldLabel,
} from "@/components/ui/field";
import { Switch } from "@/components/ui/switch";

const SwitchDemo = () => (
  <Field className="max-w-sm" orientation="horizontal">
    <FieldContent>
      <FieldLabel>Made for kids</FieldLabel>
      <FieldDescription>
        YouTube asks every stream to say whether it&apos;s made for kids.
      </FieldDescription>
    </FieldContent>
    <Switch />
  </Field>
);

export default SwitchDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/switch
```

## Usage

```tsx
import { Switch } from "@/components/ui/switch";
```

```tsx
<Field orientation="horizontal">
  <FieldLabel>Save local recording</FieldLabel>
  <Switch />
</Field>
```

A switch is the one way to turn something on or off: never an On and Off pair, and never a toggle button. In a settings list, put it in a [SettingsRow](/docs/components/field#settings-rows).

## Examples

### Sizes

`sm` is a 16 px track for a row that is denser than a page, such as a source's quick control. It is a track size, not a control height.

```tsx title="components/examples/switch-sizes.tsx"
"use client";

import { Field, FieldLabel } from "@/components/ui/field";
import { Switch } from "@/components/ui/switch";

const SwitchSizes = () => (
  <div className="flex max-w-xs flex-col gap-3">
    <Field orientation="horizontal">
      <FieldLabel>System audio</FieldLabel>
      <Switch defaultChecked />
    </Field>
    <Field orientation="horizontal">
      <FieldLabel>Show on stream</FieldLabel>
      <Switch defaultChecked size="sm" />
    </Field>
  </div>
);

export default SwitchSizes;
```

### Disabled

A disabled switch says why in its description. Disable every control a lock covers, rather than leaving one that looks enabled.

```tsx title="components/examples/switch-disabled.tsx"
"use client";

import {
  Field,
  FieldContent,
  FieldDescription,
  FieldLabel,
} from "@/components/ui/field";
import { Switch } from "@/components/ui/switch";

const SwitchDisabled = () => (
  <Field className="max-w-sm" data-disabled="true" orientation="horizontal">
    <FieldContent>
      <FieldLabel>Save local recording</FieldLabel>
      <FieldDescription>
        Locked while you&apos;re recording or live.
      </FieldDescription>
    </FieldContent>
    <Switch defaultChecked disabled />
  </Field>
);

export default SwitchDisabled;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `chrome-fill` | The track while on |
| `bg-input/90` | The recessed track while off |
| `chrome-bead` | The knob while off |
| `chrome-bead-ink` | The knob on its chrome track: black in dark, pearl in light |
| `ring-knob-ring` | The knob's hairline rim |
| `data-checked`, `data-unchecked`, `data-disabled` | The state, from Base UI |
| `data-size` | `default` (32 × 20) or `sm` (24 × 16) |

## Keyboard

| Key              | Action                          |
| ---------------- | ------------------------------- |
| <kbd>Space</kbd> | Toggles the switch              |
| <kbd>Enter</kbd> | Toggles the switch              |
| <kbd>Tab</kbd>   | Moves focus to the next control |

## Accessibility

The switch is a `role="switch"` span with `aria-checked`, beside a hidden native input that carries its form value. Its `id` goes on that hidden input, so a `FieldLabel` toggles it on click and Base UI names the switch by that label. Never put a switch inside a button or a clickable row: a control inside a control can't be reached on its own.

## API reference

Every [Base UI Switch](https://base-ui.com/react/components/switch) root prop, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"default" \| "sm"` | `"default"` | The track size. |
| `checked` | `boolean` | — | The controlled state. |
| `defaultChecked` | `boolean` | `false` | The uncontrolled starting state. |
| `onCheckedChange` | `(checked: boolean, eventDetails) => void` | — | Called with the next state. |
| `id` | `string` | — | Lands on the hidden input. Inside a Field, one is made when it is missing, and the FieldLabel points at it. |

# Tabs (/docs/components/tabs)

```tsx title="components/examples/tabs-demo.tsx"
"use client";

import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";

const TabsDemo = () => (
  <Tabs className="w-full max-w-sm" defaultValue="chat">
    <TabsList aria-label="Stream Manager panes">
      <TabsTrigger value="chat">Chat</TabsTrigger>
      <TabsTrigger value="activity">Activity</TabsTrigger>
      <TabsTrigger value="buddy">Buddy</TabsTrigger>
    </TabsList>
    <TabsContent value="chat">
      <p className="text-muted-foreground">
        Chat from YouTube and Twitch shows up here while you’re live.
      </p>
    </TabsContent>
    <TabsContent value="activity">
      <p className="text-muted-foreground">
        Follows, subscriptions and raids, newest first.
      </p>
    </TabsContent>
    <TabsContent value="buddy">
      <p className="text-muted-foreground">
        Buddy keeps the questions it heard in chat until you answer them.
      </p>
    </TabsContent>
  </Tabs>
);

export default TabsDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/tabs
```

## Usage

```tsx
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
```

```tsx
<Tabs defaultValue="chat">
  <TabsList aria-label="Stream Manager panes">
    <TabsTrigger value="chat">Chat</TabsTrigger>
    <TabsTrigger value="activity">Activity</TabsTrigger>
  </TabsList>
  <TabsContent value="chat">…</TabsContent>
  <TabsContent value="activity">…</TabsContent>
</Tabs>
```

Tabs switch a view: a page or a pane with its own content. Choosing a value among 2–4 options is [Segmented control](/docs/components/segmented-control), which wears the same track.

## Anatomy

```tsx
<Tabs>
  <TabsList>
    <TabsTrigger />
  </TabsList>
  <TabsContent />
</Tabs>
```

## Examples

### Line

`variant="line"` drops the track and underlines the active tab: for a strip of words over a pane, where a track would be one box too many.

```tsx title="components/examples/tabs-line.tsx"
"use client";

import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";

const TabsLine = () => (
  <Tabs className="w-full max-w-sm" defaultValue="upcoming">
    <TabsList aria-label="Which streams" variant="line">
      <TabsTrigger value="upcoming">Upcoming</TabsTrigger>
      <TabsTrigger value="past">Past</TabsTrigger>
    </TabsList>
    <TabsContent value="upcoming">
      <p className="text-muted-foreground">
        Friday Q&amp;A starts at 6:00 PM on YouTube and Twitch.
      </p>
    </TabsContent>
    <TabsContent value="past">
      <p className="text-muted-foreground">
        No past streams yet. They show up here after you go live.
      </p>
    </TabsContent>
  </Tabs>
);

export default TabsLine;
```

### Vertical

`orientation="vertical"` stacks the list beside its panels, and the up and down arrows move through it.

```tsx title="components/examples/tabs-vertical.tsx"
"use client";

import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";

const TabsVertical = () => (
  <Tabs
    className="w-full max-w-md"
    defaultValue="general"
    orientation="vertical"
  >
    <TabsList aria-label="Settings">
      <TabsTrigger value="general">General</TabsTrigger>
      <TabsTrigger value="permissions">Permissions</TabsTrigger>
      <TabsTrigger value="shortcuts">Shortcuts</TabsTrigger>
    </TabsList>
    <TabsContent value="general">
      <p className="text-muted-foreground">
        Where recordings are saved, and how Videorc starts.
      </p>
    </TabsContent>
    <TabsContent value="permissions">
      <p className="text-muted-foreground">
        Camera, microphone and screen access for Videorc.
      </p>
    </TabsContent>
    <TabsContent value="shortcuts">
      <p className="text-muted-foreground">
        Every shortcut, and the keys you bound yourself.
      </p>
    </TabsContent>
  </Tabs>
);

export default TabsVertical;
```

## Theming

The track and the trigger's shape come from `tabs-variants`, shared with Segmented control: `tabsListVariants({ variant })` and `tabsTriggerBaseClassName`. Tabs re-exports `tabsListVariants`.

| Token or attribute | Meaning |
| --- | --- |
| `bg-foreground/5`, `ring-border` | The default track |
| `chrome-plate` | The active tab on the default track, keyed off `data-active` |
| `after:bg-foreground` | The line variant's underline under the active tab |
| `h-control` | The 28 px horizontal list |
| `data-active`, `data-disabled` | On a tab, from Base UI |
| `data-variant` | On the list: `default` or `line` |
| `data-orientation` | On the root, for `data-horizontal:` and `data-vertical:` styles |

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Moves focus to the active tab, then into its panel |
| `ArrowRight`, `ArrowLeft` | Moves between tabs in a horizontal list and shows each one's panel |
| `ArrowDown`, `ArrowUp` | Moves between tabs in a vertical list and shows each one's panel |
| `Home`, `End` | Moves to the first or last tab |
| `Space`, `Enter` | Shows the focused tab's panel, when `activateOnFocus` is off |

## Accessibility

Base UI wires `tablist`, `tab` and `tabpanel` with their `aria-controls` and `aria-labelledby`. Name the list with `aria-label`, or put the tabs in a [Field](/docs/components/field): the Field's label names the list unless it carries its own `aria-label`. A panel is a tab stop and shows a ring while focused.

The arrow keys show a tab's panel as they move, as Videorc's tabs always have. When showing a view is heavy, pass `activateOnFocus={false}` to the list and Enter or Space shows it instead.

## API reference

### Tabs

Every [Base UI Tabs Root](https://base-ui.com/react/components/tabs) prop. `value` and `defaultValue` take any value, not only strings.

### TabsList

Every [Base UI Tabs List](https://base-ui.com/react/components/tabs) prop, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "line"` | `"default"` | — |
| `activateOnFocus` | `boolean` | `true` | Shows a tab's panel as the arrow keys reach it. Base UI's own default is false. |

### TabsTrigger and TabsContent

Every [Base UI Tab and Panel](https://base-ui.com/react/components/tabs) prop. Both take the `value` they stand for.

# Textarea (/docs/components/textarea)

```tsx title="components/examples/textarea-demo.tsx"
"use client";

import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";
import { Textarea } from "@/components/ui/textarea";

const TextareaDemo = () => (
  <Field className="max-w-sm">
    <FieldLabel>Description</FieldLabel>
    <Textarea placeholder="Optional" />
    <FieldDescription>Shown under the livestream on YouTube.</FieldDescription>
  </Field>
);

export default TextareaDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/textarea
```

## Usage

```tsx
import { Textarea } from "@/components/ui/textarea";
```

```tsx
<Field>
  <FieldLabel>Description</FieldLabel>
  <Textarea placeholder="Optional" />
</Field>
```

## Examples

### States

Set `aria-invalid` and put a `FieldError` under it when its text is refused. A disabled textarea inside a Field says why in its description.

```tsx title="components/examples/textarea-states.tsx"
"use client";

import {
  Field,
  FieldDescription,
  FieldError,
  FieldGroup,
  FieldLabel,
} from "@/components/ui/field";
import { Textarea } from "@/components/ui/textarea";

const TextareaStates = () => (
  <FieldGroup className="max-w-sm">
    <Field>
      <FieldLabel>Description</FieldLabel>
      <Textarea aria-invalid defaultValue="Speedrun night <3" />
      <FieldError>Descriptions can&apos;t contain &lt; or &gt;.</FieldError>
    </Field>
    <Field data-disabled="true">
      <FieldLabel>Notes</FieldLabel>
      <Textarea defaultValue="Thank the raid, then switch scenes." disabled />
      <FieldDescription>
        Locked while you&apos;re recording or live.
      </FieldDescription>
    </Field>
  </FieldGroup>
);

export default TextareaStates;
```

## Theming

| Token or attribute     | Meaning                                   |
| ---------------------- | ----------------------------------------- |
| `field-sizing-content` | Grows with its text, from a 64 px minimum |
| `rounded-chip`         | The 6 px control radius                   |
| `bg-input/50`          | The recessed field fill                   |
| `text-sm`              | 14 px at every width                      |
| `aria-invalid`         | Draws the destructive border and ring     |
| `data-slot="textarea"` | The textarea, for styling from a parent   |

It doesn't resize by hand. Pass `resize-y` and a taller `min-h-*` for a long description.

## Accessibility

Inside a [Field](/docs/components/field), the `FieldLabel` names the textarea and every `FieldDescription` describes it. Outside one, pass `aria-label`, or a [Label](/docs/components/label) with `htmlFor`. An explicit `id` or `aria-describedby` always wins.

## API reference

Every `<textarea>` attribute, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | — | Kept as given. Inside a Field, one is made when it is missing, and the FieldLabel points at it. |
| `aria-describedby` | `string` | — | Replaces the Field's descriptions. |

# Toggle Group (/docs/components/toggle-group)

```tsx title="components/examples/toggle-group-demo.tsx"
"use client";

import { useState } from "react";

import { TwitchIcon, YoutubeIcon } from "@/components/icons";
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

const ToggleGroupDemo = () => {
  const [platform, setPlatform] = useState(["all"]);
  return (
    <ToggleGroup
      aria-label="Show chat from"
      // Pressing the pressed chip again clears the filter: back to All.
      onValueChange={(next) => setPlatform(next.length > 0 ? next : ["all"])}
      value={platform}
    >
      <ToggleGroupItem value="all">All</ToggleGroupItem>
      <ToggleGroupItem value="youtube">
        <YoutubeIcon data-icon="inline-start" />
        YouTube
      </ToggleGroupItem>
      <ToggleGroupItem value="twitch">
        <TwitchIcon data-icon="inline-start" />
        Twitch
      </ToggleGroupItem>
    </ToggleGroup>
  );
};

export default ToggleGroupDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/toggle-group
```

## Usage

```tsx
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";
```

```tsx
<ToggleGroup aria-label="Chat filters" multiple>
  <ToggleGroupItem value="questions">Questions</ToggleGroupItem>
  <ToggleGroupItem value="mentions">Mentions</ToggleGroupItem>
</ToggleGroup>
```

## Anatomy

```tsx
<ToggleGroup>
  <ToggleGroupItem />
</ToggleGroup>
```

## Examples

### Filter chips

`multiple` lets several chips stay on. `size="xs"` and `spacing={1}` make the dense chip row Videorc uses to choose which kinds of cuts to review; `flex-wrap` lets a narrow pane wrap it.

```tsx title="components/examples/toggle-group-filters.tsx"
"use client";

import { useState } from "react";

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

const KINDS = [
  { count: 14, id: "silences", label: "Silences" },
  { count: 9, id: "fillers", label: "Ums" },
  { count: 3, id: "retakes", label: "Retakes" },
  { count: 2, id: "false-starts", label: "False starts" },
];

const ToggleGroupFilters = () => {
  const [kinds, setKinds] = useState(["silences", "fillers"]);
  return (
    <ToggleGroup
      aria-label="Kinds of cuts"
      className="max-w-xs flex-wrap"
      multiple
      onValueChange={setKinds}
      size="xs"
      spacing={1}
      value={kinds}
    >
      {KINDS.map((kind) => (
        <ToggleGroupItem key={kind.id} value={kind.id}>
          {kind.label}
          <span className="text-muted-foreground tabular-nums">
            {kind.count}
          </span>
        </ToggleGroupItem>
      ))}
    </ToggleGroup>
  );
};

export default ToggleGroupFilters;
```

### Joined

`spacing={0}` with `variant="outline"` joins the items into one strip with shared hairlines, rounded at the ends.

```tsx title="components/examples/toggle-group-outline.tsx"
"use client";

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

const ToggleGroupOutline = () => (
  <ToggleGroup
    aria-label="Show in the preview"
    defaultValue={["safe-areas"]}
    multiple
    spacing={0}
    variant="outline"
  >
    <ToggleGroupItem value="safe-areas">Safe areas</ToggleGroupItem>
    <ToggleGroupItem value="grid">Grid</ToggleGroupItem>
    <ToggleGroupItem value="names">Source names</ToggleGroupItem>
  </ToggleGroup>
);

export default ToggleGroupOutline;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `chrome-plate` | A pressed item, keyed off `data-pressed` |
| `rounded-chip`, `rounded-row` | An item, and the ends of a joined strip |
| `h-control`, `h-6` | The `default` and `xs` item heights |
| `--gap` | The space between items, set from `spacing` |
| `data-variant`, `data-size`, `data-spacing` | On the group and every item, for styling from a parent |
| `data-orientation` | `horizontal` or `vertical`, from `orientation` |

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Moves focus into the group, then out of it |
| `ArrowRight`, `ArrowLeft` | Moves between items in a horizontal group, wrapping |
| `ArrowDown`, `ArrowUp` | Moves between items in a vertical group, wrapping |
| `Space`, `Enter` | Presses or releases the focused item |

## Accessibility

The group is a `group` and every item a `<button>` with `aria-pressed`. Name the group with `aria-label`, or put it in a [Field](/docs/components/field): its label names the group through `aria-labelledby` unless the group carries its own `aria-label`. An icon-only item needs its own `aria-label`.

ToggleGroup is for filters. Choosing exactly one value among 2–4 options is [Segmented control](/docs/components/segmented-control), which is a radio group to assistive tech.

## API reference

### ToggleGroup

Every [Base UI Toggle Group](https://base-ui.com/react/components/toggle-group) prop, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string[]` | — | The pressed items, when controlled. An array even when one item can be pressed. |
| `defaultValue` | `string[]` | — | — |
| `onValueChange` | `(value: string[], details) => void` | — | — |
| `multiple` | `boolean` | `false` | Lets several items stay pressed. Radix's type="multiple". |
| `variant` | `"default" \| "outline"` | — | Applies to every item. |
| `size` | `"default" \| "xs"` | — | Applies to every item. |
| `spacing` | `number` | `2` | The gap between items in spacing units. 0 joins them. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | — |

### ToggleGroupItem

Every [Base UI Toggle](https://base-ui.com/react/components/toggle) prop. `value` names the item in the group's array; `variant` and `size` apply when the group sets none.

# Toggle (/docs/components/toggle)

```tsx title="components/examples/toggle-demo.tsx"
"use client";

import { HiddenIcon, MarkerIcon, PinIcon } from "@/components/icons";
import { Toggle } from "@/components/ui/toggle";

const ToggleDemo = () => (
  <div className="flex items-center gap-1">
    <Toggle aria-label="Keep on top" defaultPressed>
      <PinIcon />
    </Toggle>
    <Toggle aria-label="Hide screen">
      <HiddenIcon />
    </Toggle>
    <Toggle>
      <MarkerIcon data-icon="inline-start" />
      Markers
    </Toggle>
  </div>
);

export default ToggleDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/toggle
```

## Usage

```tsx
import { Toggle } from "@/components/ui/toggle";
```

```tsx
<Toggle aria-label="Keep on top">
  <PinIcon />
</Toggle>
```

## Examples

### Outline and compact

`outline` draws a hairline around the toggle, for one that sits beside fields. `xs` (24 px) is for dense rows only. Control it with `pressed` and `onPressedChange` when the app owns the state.

```tsx title="components/examples/toggle-outline.tsx"
"use client";

import { useState } from "react";

import { Toggle } from "@/components/ui/toggle";

const ToggleOutline = () => {
  const [freeform, setFreeform] = useState(false);
  return (
    <div className="flex items-center gap-2">
      <Toggle
        onPressedChange={setFreeform}
        pressed={freeform}
        variant="outline"
      >
        Freeform
      </Toggle>
      <Toggle defaultPressed size="xs" variant="outline">
        Snap
      </Toggle>
    </div>
  );
};

export default ToggleOutline;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `chrome-plate` | The pressed fill, keyed off `data-pressed` |
| `bg-muted` | Hover. The plate means pressed, never hovered |
| `text-muted-foreground`, `text-foreground` | Resting and pressed text |
| `h-control` | The 28 px desktop control height |
| `data-pressed`, `data-disabled` | Base UI's state attributes, for styling from outside |

## Keyboard

| Key              | Action                          |
| ---------------- | ------------------------------- |
| `Space`, `Enter` | Presses or releases the toggle  |
| `Tab`            | Moves focus to the next control |

## Accessibility

Base UI renders a `<button>` with `aria-pressed`, so the state is announced on its own. An icon-only toggle needs an `aria-label` that stays the same in both states ("Keep on top", never "Unpin"). A toggle is for a mode the user turns on and off; choosing one value among a few is [Segmented control](/docs/components/segmented-control), and a setting that applies at once is a [Switch](/docs/components/switch).

## API reference

Every [Base UI Toggle](https://base-ui.com/react/components/toggle) prop, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "outline"` | `"default"` | — |
| `size` | `"default" \| "xs"` | `"default"` | — |
| `pressed` | `boolean` | — | The pressed state, when controlled. |
| `defaultPressed` | `boolean` | `false` | — |
| `onPressedChange` | `(pressed: boolean, details) => void` | — | Called when the pressed state changes. |

`toggleVariants({ variant, size })` returns the classes, for an element styled as a toggle.

# Tooltip (/docs/components/tooltip)

```tsx title="components/examples/tooltip-demo.tsx"
"use client";

import { NoteIcon, PinIcon, PreviewIcon } from "@/components/icons";
import { Button } from "@/components/ui/button";
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@/components/ui/tooltip";

const TOOLS = [
  { icon: PreviewIcon, label: "Preview" },
  { icon: NoteIcon, label: "Notes" },
  { icon: PinIcon, label: "Keep on top" },
] as const;

const TooltipDemo = () => (
  <div className="flex items-center gap-1">
    {TOOLS.map(({ icon: Icon, label }) => (
      <Tooltip key={label}>
        <TooltipTrigger
          render={<Button aria-label={label} size="icon" variant="ghost" />}
        >
          <Icon />
        </TooltipTrigger>
        <TooltipContent>{label}</TooltipContent>
      </Tooltip>
    ))}
  </div>
);

export default TooltipDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/tooltip
```

## Usage

```tsx
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip";
```

```tsx
<Tooltip>
  <TooltipTrigger
    render={<Button aria-label="Keep on top" size="icon" variant="ghost" />}
  >
    <PinIcon />
  </TooltipTrigger>
  <TooltipContent>Keep on top</TooltipContent>
</Tooltip>
```

Mount one `TooltipProvider` around each window. Tooltips under it share a delay group: once one is open, moving to the next opens it at once. A tooltip outside every provider still works, with its trigger's own 600 ms.

## Anatomy

```tsx
<TooltipProvider>
  <Tooltip>
    <TooltipTrigger />
    <TooltipContent />
  </Tooltip>
</TooltipProvider>
```

## Examples

### With a shortcut

Put a [Shortcut keys](/docs/components/shortcut-keys) chip after the label to show the bound shortcut. The tooltip tightens its end padding around the chip.

```tsx title="components/examples/tooltip-shortcut.tsx"
"use client";

import { RecordIcon, SearchIcon } from "@/components/icons";
import { Button } from "@/components/ui/button";
import { ShortcutKeys } from "@/components/ui/shortcut-keys";
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@/components/ui/tooltip";

const TooltipShortcut = () => (
  <div className="flex items-center gap-2">
    <Tooltip>
      <TooltipTrigger render={<Button variant="secondary" />}>
        <SearchIcon data-icon="inline-start" />
        Search
      </TooltipTrigger>
      <TooltipContent>
        Search Videorc
        <ShortcutKeys accelerator="CmdOrCtrl+K" />
      </TooltipContent>
    </Tooltip>
    <Tooltip>
      <TooltipTrigger render={<Button variant="record" />}>
        <RecordIcon data-icon="inline-start" weight="fill" />
        Record
      </TooltipTrigger>
      <TooltipContent side="bottom">
        Start recording
        <ShortcutKeys accelerator="CmdOrCtrl+Shift+R" />
      </TooltipContent>
    </Tooltip>
  </div>
);

export default TooltipShortcut;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `glass-float-tooltip` | The tooltip tier: the window's solid tone, a 1 px rim and the float drop |
| `rounded-row` | 8 px corners |
| `text-xs` | 12 px text, never an inverted pill |
| `data-open`, `data-closed` | Fades and scales from 0.98 in 100 ms, with no slide |
| `data-side` | The side it opened on |

## Keyboard

| Key      | Action                                 |
| -------- | -------------------------------------- |
| `Tab`    | Focusing the trigger opens its tooltip |
| `Escape` | Closes the tooltip                     |

## Accessibility

A tooltip is never the only place a fact lives, and `title=` is not an information channel. An icon-only trigger still needs its own `aria-label`: the tooltip repeats the name for sighted users. A disabled control takes no hover, so explain it with [Disabled reason](/docs/components/disabled-reason).

## API reference

Every [Base UI Tooltip](https://base-ui.com/react/components/tooltip) prop, plus:

### TooltipProvider

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `delay` | `number` | `600` | Milliseconds before a tooltip opens on hover. |
| `closeDelay` | `number` | `0` | Milliseconds before a tooltip closes. |
| `timeout` | `number` | `400` | Within this many milliseconds of one closing, the next opens at once. |

### TooltipContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"top"` | — |
| `sideOffset` | `number` | `0` | — |
| `align` | `"start" \| "center" \| "end"` | `"center"` | — |
| `alignOffset` | `number` | `0` | — |

# Design language (/docs/concepts/design-language)

Videorc is a desktop app, not a web page. Every window sits on its own ground, panes are flush and split by hairlines, controls are desktop-sized, and color is information.

The reference is Videorc's logo: black metal with soft silver streaks, polished chrome on the controls you touch, and one LED-red accent. Every window shares one material and one set of rules, which is why the design is called the window family.

## Dark first, light as its twin

Dark is the reference. Light is the same structure with the light token column, never a separately designed theme: porcelain with graphite streaks and black-chrome controls, the dark chrome turned the other way around.

Every token has a dark and a light value. A component never checks which theme is on; it reads the tokens, and the `.dark` class swaps them.

## Color is information

The chrome is monochrome, and every neutral is truly neutral (chroma 0, no blue or warm cast). Saturated color appears only where it means something:

| Color | Token | Means |
| --- | --- | --- |
| Red | `--live`, `--destructive` | Record, on air, failed, destructive. The logo's LED red |
| Green | `--success` | Healthy, connected |
| Amber | `--warning` | Needs attention |
| Blue | `--info` | Neutral news. Rare |
| Brand colors | `--color-platform-*` | Source and platform icons, the only large color on screen |

- Never tint a panel, a row or text for decoration.
- Never color a status word. The tone rides on an icon, a dot, a chip or an alert, and the word stays monochrome.
- There's no colored action accent. The primary action is chrome, not blue.

## The window and its coats

Every Videorc window is opaque and paints the theme's plain solid: #070707 in dark, #FAFAFA in light, the same on every platform. Chrome lives in the controls and the chrome rows, never behind them.

Each region paints a coat of the theme's solid tone. How much of the solid a region paints is its cover:

| Region          | Utility            | Cover, dark | Cover, light |
| --------------- | ------------------ | ----------- | ------------ |
| The window body | `bg-glass-window`  | 82%         | 86%          |
| The sidebar     | `bg-glass-sidebar` | 88%         | 92%          |
| Content panes   | `bg-glass-content` | 82%         | 86%          |

The body paints the lighter cover, and the sidebar and content panes add exactly the delta that brings them to theirs. The sidebar is the heavier region. On the solid window every region composites to the solid; the covers still decide the frost when something translucent sits behind.

- **Never stack a third coat.** Each region composites to exactly its cover. A coated card on a coated pane comes out darker than anything was tuned for.
- **Change covers, not coats.** The coats are derived from `--glass-cover-sidebar` and `--glass-cover-work`. See [Theme](/docs/concepts/theme).
- **Contrast is measured, not eyeballed.** Each text tier is checked over the solid and at Increase Contrast: primary at 7:1, secondary at 4.5:1, tertiary at 3:1.
- **No `backdrop-filter`, anywhere.** On an Electron window with a native material, a CSS backdrop blur shows in Chromium's own screenshots but never reaches the display, and in Videorc it once froze the compositor. A live blur also costs GPU time on every frame, which a recording app can't spare.

## Floating glass

What floats is flat and opaque: a tier of the window's solid tone with a 1 px rim and a drop shadow. No sheen, no highlight, no blur. Without a frost, any translucency only leaks: at 97% opacity, the white text under a hover card still reads through.

| Utility | For | Dark | Light |
| --- | --- | --- | --- |
| `glass-float` | Menus, selects, popovers, hover cards, chart tooltips, toasts | About `#1D1D1D` | Porcelain |
| `glass-float-dialog` | Dialogs and the command palette | About `#161616` | Porcelain, with a deeper drop |
| `glass-float-tooltip` | Tooltips | The solid itself | Porcelain |

- Pair each with `border`: the utility sets the rim's color, and the element brings its width.
- One surface per float. A `Command` inside a [Dialog](/docs/components/dialog) stays transparent.
- Never `bg-popover` with a ring or a shadow. In this theme `--popover` follows `glass-float`, so a freshly added shadcn component still lands on the right tone.

## Chrome materials

The controls you touch shine, and nothing else does. Light is the crisp invert: black chrome on porcelain.

| Utility | What it is | Who wears it |
| --- | --- | --- |
| `chrome-fill` | The polished primary fill | [Button](/docs/components/button) `default`, a checked checkbox, a switch that's on, progress, slider ranges |
| `chrome-plate` | Selected or active | The active segment of a [SegmentedControl](/docs/components/segmented-control), the active tab, a pressed toggle, the sidebar's current page |
| `chrome-bead`, `chrome-bead-ink` | Knobs and thumbs | Slider thumbs and the switch knob; `-ink` is the dark bead for a knob on a chrome track |
| `chrome-led` | Metallic red | Button `record` only: Record and its stop button. `data-lit` lights it and makes it glow while a recording or livestream runs |

- **Only components wear materials.** A screen gets the shine through a component's variant, never by adding a class.
- **Everything else stays flat.** Panels, sections, rows, menus, dialogs, toasts and text never take a material or a gradient. No gradient text, no sheen on toolbars or panes.
- **States.** A fill lifts a little on hover and turns concave when pressed. Disabled is flat. Hover on a plated segment stays the flat `bg-accent`, because the plate means selected.
- **Lit red only ever means record or live.** Delete stays `destructive`, never `record`.
- The materials write into Tailwind's shadow stack, so a `ring-*` focus ring still draws over them.

## Glass chips and tones

Badges, status pills, tags and key chips are small pieces of the window glass: a gradient fill, a 1 px rim, a top highlight and a soft drop. They never move and never blur.

| Utility | What it is |
| --- | --- |
| `glass-chip` | A neutral chip: a [Badge](/docs/components/badge), a secondary [Button](/docs/components/button) |
| `glass-chip-tinted` | An emphasis chip: the tone tints the glass. Only for failed, on air and destructive |
| `glass-dot` | A status dot: the tone, a 2 px halo and a soft glow |
| `glass-keycap` | A key, not a tag: a brighter top edge and a dark bottom edge. [Kbd](/docs/components/kbd) wears it |

Color rides in one variable, `--chip-tone`, which a tone utility sets:

| Utility            | Means                         |
| ------------------ | ----------------------------- |
| `tone-success`     | Healthy, connected            |
| `tone-warning`     | Needs attention               |
| `tone-destructive` | Failed                        |
| `tone-live`        | On air, recording             |
| `tone-info`        | Neutral news                  |
| `tone-neutral`     | Idle: a gray dot with no glow |

A status chip keeps monochrome text and shows its tone in a 6 px dot. Only an emphasis chip tints the glass itself. Reach for [Badge](/docs/components/badge) rather than a hand-rolled pill.

## Three text tiers

| Utility | Tier | For |
| --- | --- | --- |
| `text-foreground` | Primary | Titles, labels, values |
| `text-muted-foreground` | Secondary | Descriptions, metadata, placeholders, and every fact the user needs |
| `text-subtle` | Tertiary | Section labels, quiet hints, disabled text |

Three tiers, nothing else. Essential information never goes in `text-subtle`: a reason, a limit, a status or a value is secondary or primary. The tertiary tier passes AA on the solid, but holds only 3:1 over the ground's worst pixel.

No text is smaller than 11 px. The sizes are tokens: see [Desktop scale](/docs/concepts/desktop-scale#type).

## Radius tiers

| Utility         | Size  | For                      |
| --------------- | ----- | ------------------------ |
| `rounded-panel` | 12 px | Containers, dialogs      |
| `rounded-row`   | 8 px  | Rows, cards, tooltips    |
| `rounded-chip`  | 6 px  | Controls, key chips      |
| `rounded-tag`   | 7 px  | Tags                     |
| `rounded-lg`    | 10 px | Menus, selects, popovers |

Status chips are fully round. Window corners belong to the OS. There are no ad hoc radii.

## Motion

Fast and subtle: 100–150 ms, ease-out. Floating surfaces fade and scale from 0.98, and rows highlight instantly. Nothing bounces, chips never move, and a button doesn't shift when pressed. The ground is a still.

When the system asks to reduce motion, the theme collapses every CSS transition and animation. For motion CSS can't see, such as a script-driven scroll, use [useReducedMotion](/docs/hooks/use-reduced-motion).

## Keyboard first

Every primary action has a shortcut, and shows it as a key chip. Global hints live in the [status bar](/docs/primitives/status-bar), not on every surface.

- Write a shortcut once, as an Electron accelerator (`CmdOrCtrl+Shift+J`), and print it with [ShortcutKeys](/docs/components/shortcut-keys): ⇧⌘J on macOS, Ctrl+Shift+J on Windows and Linux. Never type ⌘ or "Cmd+" by hand.
- A global key never fires from a text field or from under an open dialog or menu. See [Modal open](/docs/hooks/modal-open).
- A [tooltip](/docs/components/tooltip) carries a control's name and its shortcut. A tooltip is never the only place a fact lives.
- The focus ring shows on keyboard focus only.

## Toast discipline

A toast is for news the interface doesn't already show. When in doubt, don't toast: someone mid-task reads every popup as an interruption.

- **No success toast for a change the user just watched happen.** In Videorc, switching a scene, a layout or a source never toasts: the stage is the confirmation.
- **Type by meaning.** The type colors the 16 px icon only, never the panel, its rim or its text. The theme makes [Sonner](/docs/components/sonner) toasts neutral glass even with `richColors`.

| Type | When |
| --- | --- |
| Error | It failed, and needs you |
| Warning | It can't happen now, or it's degraded. A refusal is a warning, never an error |
| Info | Neutral news, or a step to take somewhere else |
| Success | Something finished out of view: a recording saved, an import done, an account connected |

- The title is the outcome, with no period: "MP4 ready", "Couldn't import the image". The description is whole sentences. Add at most one action, named by its verb: "Retry", "Show in Finder".
- About 4 seconds for one line, 8 or more with a description, and until it's dismissed when it has an action.
- One id per kind of toast, so a newer one replaces the older and the same news never stacks.

## One primitive per job

Each job has one shared primitive. Screens compose them; they don't restyle them. If a primitive lacks something, extend it a little rather than hand-roll a competitor.

| Need | Use |
| --- | --- |
| Page sections | [PanelSection](/docs/primitives/panel-section) |
| A list of like things | A `GroupedList` of [ListRow](/docs/primitives/list-row)s |
| Global state and hints | [StatusBar](/docs/primitives/status-bar) |
| A destructive confirmation | [ConfirmDialog](/docs/primitives/confirm-dialog) |
| Any other modal | [Dialog](/docs/components/dialog) |
| A choice of 2 to 4 values | [SegmentedControl](/docs/components/segmented-control) |
| Per-item actions | [DropdownMenu](/docs/components/dropdown-menu) |
| Why a control is disabled | [DisabledReason](/docs/components/disabled-reason) |
| A shortcut | [ShortcutKeys](/docs/components/shortcut-keys) |
| Status, tags and counts | [Badge](/docs/components/badge) |
| News | [Sonner](/docs/components/sonner) |

## Words

The copy on these surfaces follows a few rules:

- Sentence case everywhere: "Save local recording". Capitalize names only.
- Plain, short and specific. Say what happened, then what to do. Use contractions and American English, and no em dashes.
- One "…" character, never three dots. It goes on a command that asks for more ("Rename…") and on a pending label ("Saving…").
- "Choose", not "Select". Delete destroys; Remove takes something out of a list.
- A disabled control always says why.
- An error names what failed ("Couldn't import the image"), then why, then one fix.

# Desktop scale (/docs/concepts/desktop-scale)

A desktop app is denser than a web page, on purpose:

- **A pointer, not a finger.** A mouse or trackpad hits a 28 px control easily. A 44 px touch target spends room a pointer doesn't need.
- **Windows share the screen.** A recording app sits beside the thing it records, often in a fraction of the display. Its controls should leave room for the preview, the chat and the work.
- **It matches the OS.** Native controls on macOS and Windows are in the same range, so the app reads as part of the desktop rather than a site in a frame.
- **It's used for hours, by people who know it.** Dense, steady layouts and keyboard shortcuts serve repeat use better than big, airy ones.

Density comes from structure, not from smaller text. Body text stays 14 px.

## The scale

| Utility | Size | For |
| --- | --- | --- |
| `h-control`, `size-control` | 28 px | Every control: a button, an input, a select trigger, a toggle |
| `h-row` | 32 px | A list row |
| `h-row-compact` | 28 px | A compact row: the sidebar, a dense list |
| `h-toolbar` | 40 px | A pane's toolbar and a window's title row |
| `h-status-bar` | 26 px | The status bar |
| `px-gutter` | 16 px | The pane gutter |

They're Tailwind spacing tokens, so every spacing utility takes them: `min-h-row`, `gap-gutter`, `py-gutter`. Change one in the [theme](/docs/concepts/theme) and every screen follows.

## Controls

- **28 px is the default** for a [button](/docs/components/button), an input, a select trigger and a toggle. It's set once, in the component; a screen never sets a control's height.
- **One compact size, `xs`, at 24 px.** Use it only where a control sits inside something denser than a page:
  - an alert's action;
  - a row's trailing or hover actions;
  - a card's actions;
  - a status bar or a dense side pane;
  - a small inline action under a field, such as Reset.
- **A page's or a dialog's own actions stay 28 px,** and so does a control beside a 28 px control in the same row.
- **`lg`, 32 px,** is for a dialog's or a card's single call to action.
- **There's no `sm`.** It would be 28 px under another name. A [badge](/docs/components/badge) has one size, 20 px.

## Type

| Utility | Size | Weight | For |
| --- | --- | --- | --- |
| `text-label` | 11 px | 600 | Section labels, in the tertiary tier |
| `text-meta` | 12 px | Regular | Descriptions and metadata |
| `text-section` | 13 px | 600 | Section headers |
| `text-sm` | 14 px | Regular | Body text |
| `text-sm font-semibold` | 14 px | 600 | A page or window title |

No text is smaller than 11 px, and an arbitrary `text-[13px]` never stands in for a token. The font is the system stack: SF Pro on macOS, Segoe UI on Windows.

## Radius

| Utility         | Size  | For                      |
| --------------- | ----- | ------------------------ |
| `rounded-panel` | 12 px | Containers, dialogs      |
| `rounded-row`   | 8 px  | Rows, cards, tooltips    |
| `rounded-chip`  | 6 px  | Controls, key chips      |
| `rounded-tag`   | 7 px  | Tags                     |
| `rounded-lg`    | 10 px | Menus, selects, popovers |

Menu items are 6 px inside a 4 px inset, so the corners stay concentric with their 10 px menu. Status chips are fully round, and window corners belong to the OS.

## Layout

- **No page column.** Content fills its pane edge to edge, with the 16 px gutter.
- **Flush panes.** Panes are split by 1 px hairlines. Inside a window there are no floating panels, no shadows and no big cards.
- **Flush sections.** A 13 px header, a 12 px description, a hairline between sections and 16 px of padding. No border, background, radius or shadow. See [PanelSection](/docs/primitives/panel-section).
- **Lists, not card stacks.** Like things are one grouped list of 32 px rows with hairline separators. See [ListRow](/docs/primitives/list-row). Cards are only for objects with a picture.
- **The toolbar holds the title.** Actions live with the content they act on.
- **The status bar** carries the state on the left and quiet shortcut hints on the right. See [StatusBar](/docs/primitives/status-bar).

## The one exception

The ⌘K command palette keeps a larger, launcher-sized scale: an 18 to 20 px search field and 40 px rows. It's read at a glance and gone again. Nothing else uses that scale.

# Desktop base (/docs/concepts/desktop)

A desktop app isn't a page. Dragging across a toolbar shouldn't highlight its labels, buttons don't turn the pointer into a hand, and the window doesn't bounce past its edges. The desktop base gives an Electron or Tauri app that feel in a few base rules.

It's separate from the [theme](/docs/concepts/theme) so a website can wear the tokens and keep selectable text. This docs site uses the theme without it.

## Installation

```npm
npx shadcn@latest add @videorc/desktop
```

## What it does

| Rule | Why |
| --- | --- |
| `html { user-select: none }` | Chrome text (labels, buttons, headings) doesn't select when you drag across the window, as in a native app |
| `html { cursor: default }` | The arrow is the pointer. Desktop controls don't switch to the hand, which is why videorc/ui never uses `cursor-pointer` |
| `html { overscroll-behavior: none }` | The window doesn't rubber-band past its edges |
| `input, textarea, [contenteditable="true"] { user-select: text }` | Fields always select |
| `img { -webkit-user-drag: none }` | Images don't drag out of the window |

The whole item is one base layer:

```css
@layer base {
  html {
    user-select: none;
    -webkit-user-select: none;
    cursor: default;
    overscroll-behavior: none;
  }
  input,
  textarea,
  [contenteditable="true"] {
    user-select: text;
    -webkit-user-select: text;
  }
  img {
    -webkit-user-drag: none;
  }
}
```

## Making content selectable

Content people copy opts back in with `select-text`: chat messages, notes, transcripts, logs, error details. Put it on the element, or on a container to cover everything inside.

```tsx
<p className="select-text">{message.text}</p>
```

Copy that's useful to grab, such as a stream key or a file path, is better served by a copy button next to it than by asking someone to drag across it.

## When not to use it

- **On a website or a docs site.** Readers expect to select and copy any text, and to see the hand over a link.
- **In a window that's mostly content.** A document viewer or a log window would opt back in almost everywhere; leave the base out there, or scope `select-text` to the content pane.
- **In a component embedded in someone else's page.** The rules sit on `html`, so they'd change the whole host page.

# Using it in Electron (/docs/concepts/electron)

Videorc runs these components in Electron, in a React renderer built with Vite and `rsc: false`. Nothing in the registry imports `next/*` or Electron, so the same steps work for electron-vite, Electron Forge's Vite plugin or a plain Vite app.

## Set up the renderer

### Point components.json at the renderer

Paths and aliases are relative to the renderer's source. With electron-vite's layout:

```json title="components.json"
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "base-rhea",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "src/renderer/src/styles.css",
    "baseColor": "stone",
    "cssVariables": true
  },
  "iconLibrary": "phosphor",
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "registries": {
    "@videorc": "https://ui.videorc.com/r/{name}.json"
  }
}
```

### Resolve the `@` alias

Vite resolves it in the renderer's config:

```ts title="electron.vite.config.ts"
import { resolve } from "node:path";

import tailwindcss from "@tailwindcss/vite";
import react from "@vitejs/plugin-react";
import { defineConfig } from "electron-vite";

export default defineConfig({
  // main and preload stay as they are
  renderer: {
    plugins: [react(), tailwindcss()],
    resolve: {
      alias: { "@": resolve("src/renderer/src") },
    },
  },
});
```

TypeScript resolves it through `paths`. Add them to the renderer's tsconfig and to the root `tsconfig.json`, which the shadcn CLI reads:

```json title="tsconfig.json"
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/renderer/src/*"]
    }
  }
}
```

### Import shadcn's variants

The renderer's stylesheet needs `shadcn/tailwind.css` after Tailwind. The theme lands below these lines.

```css title="src/renderer/src/styles.css"
@import "tailwindcss";
@import "tw-animate-css";
@import "shadcn/tailwind.css";

@custom-variant dark (&:is(.dark *));
```

### Add the theme and the desktop base

```npm
npx shadcn@latest add @videorc/theme @videorc/desktop
```

The [desktop base](/docs/concepts/desktop) makes the window behave like an app: chrome text doesn't select, the arrow stays the pointer, and nothing rubber-bands.

### About `"use client"`

Registry files that run in the browser start with `"use client"`, and the CLI keeps the directive even for `rsc: false` projects. Vite ignores it, so it's harmless. Leave it in: a file that matches the registry exactly diffs cleanly the next time you sync.

## The window's background

Videorc's surfaces are translucent coats that composite to the theme's solid. The window itself is opaque and paints that solid. There's no vibrancy, no Mica and no `transparent: true`, so the desktop never shows through and nothing depends on the wallpaper or the compositor.

Give the window the theme's solid as its background, so the first frame is already the right tone:

```ts title="src/main/index.ts"
const mainWindow = new BrowserWindow({
  // --glass-solid: #070707 in dark, #FAFAFA in light
  backgroundColor: nativeTheme.shouldUseDarkColors ? "#070707" : "#FAFAFA",
});
```

Don't reach for `backdrop-filter` to add a frost. On a window with a native material, a CSS backdrop blur shows in Chromium's own screenshots but never reaches the display.

The theme sets `color-scheme` on `body`. Don't set it inline on `<html>`: a root `color-scheme: light` makes Chromium paint an opaque canvas over the window.

## Platform glyphs

Shortcuts and OS words depend on the platform: ⌘ or Ctrl, Finder or Explorer, Trash or Recycle Bin. [Platform](/docs/hooks/platform) works it out in this order:

1. the platform you pass, such as Electron's `process.platform`;
2. `data-platform` on `<html>`;
3. the user agent.

Set `data-platform` before the first paint, so a Mac never flashes "Ctrl". Use a small script file in the `<head>`, not a module, so it runs before the page draws. A file also passes a strict Content Security Policy where an inline script wouldn't.

```js title="src/renderer/public/platform.js"
const agent = navigator.userAgent;
let platform = "linux";
if (agent.includes("Macintosh")) {
  platform = "darwin";
} else if (agent.includes("Windows")) {
  platform = "win32";
}
document.documentElement.dataset.platform = platform;
```

```html title="src/renderer/index.html"
<head>
  <script src="/platform.js"></script>
</head>
```

When your app knows the platform for sure (from `process.platform`, passed through your preload), pass it in: `<ShortcutKeys accelerator="CmdOrCtrl+K" platform={platform} />`.

The theme can't ship a custom variant, so add one yourself for Windows-only chrome. It keys on the same attribute, so it never pops in:

```css title="src/renderer/src/styles.css"
@custom-variant win32 (&:is([data-platform="win32"] *));
```

```tsx
<div className="hidden win32:flex">…</div>
```

## Accelerators

Write every shortcut once, as an Electron accelerator, the same string you give a menu item or `globalShortcut`:

```ts title="src/main/menu.ts"
const streamManagerItem: MenuItemConstructorOptions = {
  accelerator: "CmdOrCtrl+Shift+J",
  click: openStreamManager,
  label: "Stream Manager",
};
```

Then print it in the renderer with [ShortcutKeys](/docs/components/shortcut-keys):

```tsx
<ShortcutKeys accelerator="CmdOrCtrl+Shift+J" />
```

That reads ⇧⌘J on macOS and Ctrl+Shift+J on Windows and Linux, the way each platform's menus print it. In running text, use `shortcutLabel` from [platform](/docs/hooks/platform), and `shortcutAriaKeys` for `aria-keyshortcuts`. Keep the accelerators in one table that main and the renderer both import, so a menu and its key chip can't disagree. [Accelerator](/docs/hooks/accelerator) parses every spelling Electron accepts.

## Electron state comes in through props

Registry components never call `window.*` bridges, `ipcRenderer` or anything else Electron. Whatever Electron knows (the platform, whether a window is pinned, the list of cameras) comes in as props, and changes go out as callbacks. Your screens talk to the preload API:

```tsx
function KeepOnTopButton() {
  const [pinned, setPinned] = useState(false);
  const togglePinned = () => {
    // The screen talks to Electron; the button only sees a prop and a callback.
    window.desktop.setAlwaysOnTop(!pinned);
    setPinned(!pinned);
  };
  return (
    <Button aria-pressed={pinned} onClick={togglePinned} variant="ghost">
      Keep on top
    </Button>
  );
}
```

Here `window.desktop` stands for your own preload API. Keeping it out of the components means they render the same in a browser, in tests and in these docs, and the registry never learns your IPC names.

## Keeping your copy in sync

The registry stays the source of a component after you install it. To pull a newer version, add it again with `--overwrite`:

```npm
npx shadcn@latest add @videorc/button --overwrite
```

Then run your formatter on the files it touched, so the diff shows only real changes, and review it. Don't edit a synced file in place: change it upstream, or stop syncing that item, as Videorc does with its own icon set.

# Icons (/docs/concepts/icons)

## Installation

```npm
npx shadcn@latest add @videorc/icons
```

This adds `components/icons.tsx` and installs `@phosphor-icons/react`.

## Meaning over shape

Every videorc/ui component imports its icons from `@/components/icons`, by meaning: `SourcesIcon`, `AlertIcon`, `RecordIcon`. Nothing imports `@phosphor-icons/react` directly.

- **Swapping is a one-line change.** Point `SourcesIcon` at a different glyph and every component that shows sources follows.
- **The set stays countable.** 97 slots over 93 glyphs, reviewable in one file.
- **One glyph per meaning.** A triangle warns (`WarningIcon`), a circle alerts (`AlertIcon`), a crossed circle is an error (`ErrorIcon`). Before adding a slot, check whether one already means what you need; never add a second variant of a meaning.
- **Copy names what an icon shows,** never its slot: "Trash", not "DeleteIcon".

## Usage

```tsx
import { RecordIcon, SettingsIcon } from "@/components/icons";
```

Inside a button, mark an icon's position with `data-icon` so the padding adjusts. The button sizes its icons: 16 px, or 12 px at `xs`.

```tsx
<Button variant="record">
  <RecordIcon data-icon="inline-start" weight="fill" />
  Record
</Button>
```

An icon-only button needs an `aria-label`. Icons inside a labelled button are decorative.

```tsx
<Button aria-label="Settings" size="icon" variant="ghost">
  <SettingsIcon />
</Button>
```

`weight` is Phosphor's: `thin`, `light`, `regular` (the default), `bold`, `fill` or `duotone`. Videorc uses `fill` for the active page in navigation and for status icons. A single-weight set can accept `weight` and ignore it.

Inline and status icons are 16 px and take the secondary text color unless they carry a status. Icons draw in `currentColor`, so they follow their text.

## The set

The slots are grouped as they are in `components/icons.tsx`. Some slots share a glyph today (`StudioIcon` and `CameraIcon`, `SourcesIcon` and `DisplayIcon`, `AssetsIcon` and `ImageIcon`, `OutputIcon` and `RecordIcon`); they're separate slots so they can diverge without touching a component.

### Navigation

One slot per sidebar destination in Videorc.

| Slot | Glyph | Meaning |
| --- | --- | --- |
| `StudioIcon` | VideoCamera | The Studio, where you record and go live |
| `SourcesIcon` | Monitor | Sources: screens, windows, cameras, microphones |
| `SceneIcon` | SquaresFour | Scenes and their layouts |
| `AssetsIcon` | ImageSquare | Assets: the media you put on stream |
| `LivestreamIcon` | Broadcast | Livestream setup and destinations |
| `CaptionsIcon` | ClosedCaptioning | Captions |
| `OutputIcon` | Record | Output: where recordings go |
| `LibraryIcon` | FilmReel | The library of recordings |
| `SettingsIcon` | GearSix | Settings |
| `HealthIcon` | Pulse | Health: whether everything is working |

### Status

| Slot            | Glyph         | Meaning                              |
| --------------- | ------------- | ------------------------------------ |
| `WarningIcon`   | Warning       | Needs attention. The triangle warns  |
| `AlertIcon`     | WarningCircle | A notice to read. The circle alerts  |
| `ErrorIcon`     | XCircle       | It failed                            |
| `SuccessIcon`   | CheckCircle   | It finished, or it's healthy         |
| `CheckIcon`     | Check         | Checked, chosen, copied              |
| `InfoIcon`      | Info          | More information                     |
| `SpinnerIcon`   | CircleNotch   | Work in progress, spinning           |
| `HeartbeatIcon` | Heartbeat     | A live signal, such as stream health |
| `GaugeIcon`     | Gauge         | A measured level, such as bitrate    |
| `DisabledIcon`  | MinusCircle   | Off or unavailable                   |

### Chrome and controls

| Slot | Glyph | Meaning |
| --- | --- | --- |
| `ChevronDownIcon` | CaretDown | Opens downward: a select, a collapsible |
| `ChevronUpIcon` | CaretUp | Collapses, or scrolls up |
| `ChevronRightIcon` | CaretRight | Goes deeper: a row that navigates, a submenu |
| `CloseIcon` | X | Closes a dialog, a toast, a panel |
| `MoreIcon` | DotsThree | More actions, the ⋯ menu |
| `SearchIcon` | MagnifyingGlass | Finds |
| `ZoomInIcon` | MagnifyingGlassPlus | Opens a small picture larger. Never a zoom level control |
| `AdjustIcon` | SlidersHorizontal | Adjusts: filters, levels, options |
| `LayoutIcon` | Layout | A layout |

### Arrows and movement

| Slot | Glyph | Meaning |
| --- | --- | --- |
| `ArrowUpIcon` | ArrowUp | Up, move up |
| `ArrowDownIcon` | ArrowDown | Down, move down |
| `ArrowLeftIcon` | ArrowLeft | Back |
| `ArrowRightIcon` | ArrowRight | Forward, next |
| `ExternalLinkIcon` | ArrowSquareOut | Opens outside the app, in the browser |
| `RefreshIcon` | ArrowClockwise | Reload this |
| `SyncIcon` | ArrowsClockwise | Sync with somewhere else |
| `ResetIcon` | ArrowCounterClockwise | Back to the default |
| `SortIcon` | ArrowsDownUp | Sort order |

### Capture, media and playback

| Slot | Glyph | Meaning |
| --- | --- | --- |
| `CameraIcon` | VideoCamera | A camera |
| `DisplayIcon` | Monitor | A display or a screen to capture |
| `DesktopIcon` | Desktop | This computer |
| `MobileIcon` | DeviceMobile | A phone |
| `MicrophoneIcon` | Microphone | A microphone |
| `SpeakerOnIcon` | SpeakerHigh | Sound on |
| `SpeakerOffIcon` | SpeakerSlash | Sound off |
| `WaveformIcon` | Waveform | Audio, a level |
| `WaveformMutedIcon` | WaveformSlash | Audio muted |
| `RecordIcon` | Record | Record |
| `StopIcon` | Stop | Stops capture: a recording or a livestream |
| `PlayIcon` | Play | Plays |
| `PauseIcon` | Pause | Pauses a player. Stop is the capture action |
| `VideoFileIcon` | FileVideo | A video file |
| `ClapperboardIcon` | FilmSlate | A recording |
| `FrameIcon` | FrameCorners | The output frame |
| `CrosshairIcon` | Crosshair | A position or a target |
| `MarkerIcon` | BookmarkSimple | A marker: a point on a recording to find again. Never scissors |
| `HiddenIcon` | EyeSlash | The screen is hidden from viewers. Never the eye that opens the preview |

### Files, assets and editing

| Slot | Glyph | Meaning |
| --- | --- | --- |
| `FolderIcon` | FolderOpen | A folder, or showing a file in the file manager |
| `DownloadIcon` | DownloadSimple | Download, export |
| `UploadIcon` | UploadSimple | Upload, import |
| `SaveIcon` | FloppyDisk | Save |
| `DeleteIcon` | Trash | Delete |
| `CopyIcon` | Copy | Copy |
| `EditIcon` | PencilSimple | Edit, rename |
| `NoteIcon` | NotePencil | Notes |
| `ImageIcon` | ImageSquare | An image |
| `ImageBrokenIcon` | ImageBroken | An image that couldn't load |
| `PreviewIcon` | Eye | The preview window |

### Account, access and links

| Slot          | Glyph      | Meaning      |
| ------------- | ---------- | ------------ |
| `LockIcon`    | LockKey    | Locked       |
| `SignInIcon`  | SignIn     | Sign in      |
| `SignOutIcon` | SignOut    | Sign out     |
| `AccountIcon` | UserCircle | Your account |
| `LinkIcon`    | LinkSimple | A link       |

### Livestream audience

What viewers do for the stream, as the Stream Manager's stats bar and Activity show it.

| Slot          | Glyph | Meaning                                     |
| ------------- | ----- | ------------------------------------------- |
| `ViewersIcon` | User  | People watching now. Never your own account |

### AI, tooling and appearance

| Slot            | Glyph           | Meaning                          |
| --------------- | --------------- | -------------------------------- |
| `SparkleIcon`   | Sparkle         | An AI feature                    |
| `ClipIcon`      | Scissors        | Cutting only: clips, a clean cut |
| `RepairIcon`    | Wrench          | Repair, fix                      |
| `BugIcon`       | Bug             | Report a bug                     |
| `TerminalIcon`  | TerminalWindow  | Logs, a developer console        |
| `TextIcon`      | TextAa          | Text and typography              |
| `ChatIcon`      | ChatCircle      | Chat                             |
| `SendIcon`      | PaperPlaneRight | Send                             |
| `PinIcon`       | PushPin         | Pin, keep on top                 |
| `LightModeIcon` | Sun             | Light appearance                 |
| `DarkModeIcon`  | Moon            | Dark appearance                  |

### Platform marks

| Slot            | Glyph         | Meaning   |
| --------------- | ------------- | --------- |
| `YoutubeIcon`   | YoutubeLogo   | YouTube   |
| `XPlatformIcon` | XLogo         | X         |
| `TwitchIcon`    | TwitchLogo    | Twitch    |
| `TiktokIcon`    | TiktokLogo    | TikTok    |
| `InstagramIcon` | InstagramLogo | Instagram |
| `FacebookIcon`  | FacebookLogo  | Facebook  |

Platform and source marks are the only full-color icons on screen. The theme carries brand tints for them (`text-platform-youtube`, `text-platform-twitch`, `text-platform-instagram`, `text-platform-facebook`). Each mark is its owner's trademark, with its own rules: see [License](#license).

## AppIcon and AppIconProps

```ts
export type AppIconProps = {
  size?: number | string;
  weight?: "thin" | "light" | "regular" | "bold" | "fill" | "duotone";
} & Omit<SVGProps<SVGSVGElement>, "ref" | "weight">;

export type AppIcon = ComponentType<AppIconProps>;
```

`AppIcon` is the type of every slot. Use it wherever you store an icon, such as a nav item or a row's metadata:

```tsx
import type { AppIcon } from "@/components/icons";
import { CameraIcon, MicrophoneIcon } from "@/components/icons";

const devices: { icon: AppIcon; label: string }[] = [
  { icon: CameraIcon, label: "Camera" },
  { icon: MicrophoneIcon, label: "Microphone" },
];
```

The type is declared in the file, not re-exported from Phosphor, so your code depends on your own contract. The file's `IconSetCheck` type proves at compile time that every Phosphor glyph it exports accepts `AppIconProps`.

## Swapping a glyph or the whole set

The export names are the contract. Change what's behind a name in your copy of `components/icons.tsx`, and every component keeps working as long as each name still exports an `AppIcon`.

To swap one glyph, point the slot at another Phosphor icon, and add that icon's name to the `IconSetCheck` list so the compiler checks it:

```tsx title="components/icons.tsx"
export {
  Plug as SourcesIcon,
  // …
} from "@phosphor-icons/react";
```

To use your own artwork, export a component under the slot's name. Draw in `currentColor` so it follows its text, and accept `weight` even if you ignore it:

```tsx title="components/icons.tsx"
export function SourcesIcon({
  size = "1em",
  weight: _weight,
  ...props
}: AppIconProps) {
  return (
    <svg
      fill="currentColor"
      height={size}
      viewBox="0 0 24 24"
      width={size}
      {...props}
    >
      <path d="…" />
    </svg>
  );
}
```

To swap the whole set, rewrite the exports against your icon package and keep every name. When a newer component needs a slot you don't export, your typecheck tells you.

Once you've swapped anything, stop re-adding `@videorc/icons` with `--overwrite`; bring new slots in by hand. Videorc does exactly this: its copy replaces the YouTube and X slots with each platform's official artwork.

## License

- **Phosphor is MIT.** The registry can ship it, and you can redistribute it in your app.
- **Why not a licensed set.** Videorc looked at Nucleo, whose open-source terms cap a project at 100 icons and forbid sharing or redistributing the icons. A public registry can't ship that, so the registry stays on Phosphor. A licensed set can only live in your own app's copy of `components/icons.tsx`, under your license. The same cap is one reason the set is kept small and countable.
- **Brand marks are trademarks,** not MIT. Follow each platform's brand guidelines. Videorc, for example, draws YouTube's official icon at 20 px or more and never tints it, and draws X's mark from X's brand kit in pure black or white.

# Theme (/docs/concepts/theme)

## Installation

```npm
npx shadcn@latest add @videorc/theme
```

Every component lists the theme as a dependency, so the CLI also adds it with the first component you install.

Your global stylesheet must import `shadcn/tailwind.css` after `tailwindcss`. It defines the `data-open`, `data-checked`, `data-horizontal` and other variants the components style with. Every `base-*` project has it. Keep shadcn's class-based dark variant too, so `dark:` utilities follow the same `.dark` class the tokens do:

```css title="app/globals.css"
@import "tailwindcss";
@import "tw-animate-css";
@import "shadcn/tailwind.css";

@custom-variant dark (&:is(.dark *));
```

## What gets added

The CLI merges the theme into your global stylesheet:

| Part | Where it lands | What it is |
| --- | --- | --- |
| Light tokens | `:root` | The light column: porcelain, graphite and black chrome |
| Dark tokens | `.dark` | The dark column, the reference: black glass and silver chrome |
| `@theme` mappings | `@theme inline` | Colors, radius tiers, the desktop scale, type tokens and fonts, as Tailwind utilities |
| Utilities | `@utility` blocks | `glass-*`, `chrome-*` and `tone-*` |
| Media queries | Top level | Increase Contrast and Reduce Transparency |
| Toast styles | Top level | Sonner's toasts on the float glass |
| Base layer | `@layer base` | Borders, the body coat, the focus ring, reduced motion |

The base layer:

- gives every element the border color and a ring-colored outline;
- paints `body` with the window coat (`bg-glass-window`) and primary text, so the first paint is already the theme's tone;
- sets `color-scheme` on `body`, never on the root. A root `color-scheme: light` makes Chromium paint an opaque canvas over a transparent window;
- sets the font to the system stack: SF Pro on macOS, Segoe UI on Windows;
- draws a 2 px focus ring on `:focus-visible`;
- collapses motion under `prefers-reduced-motion`.

The theme declares no `@custom-variant`. The shadcn CLI can't carry one through a registry item, so the components use built-in variants only.

## Tokens

Values are dark · light. Neutrals are OKLCH with chroma 0, written here as their lightness.

### Surfaces and coats

| Token | Utility | Dark · light | What it is |
| --- | --- | --- | --- |
| `--glass-base` |  | `0.13 0 0` · `0.985 0 0` | The solid's OKLCH components. Every coat is cut from it |
| `--glass-solid` | `bg-glass-solid` | `#070707` · `#FAFAFA` | The theme's solid tone, opaque |
| `--glass-cover-sidebar` |  | 0.88 · 0.92 | How much of the solid the sidebar paints over the ground |
| `--glass-cover-work` |  | 0.82 · 0.86 | How much of the solid the work area paints |
| `--glass-cover-body` |  | Derived | The lighter of the two covers |
| `--glass-window` | `bg-glass-window` | Derived | The body's coat |
| `--glass-sidebar` | `bg-glass-sidebar` | Derived | The sidebar's delta over the body |
| `--glass-content` | `bg-glass-content` | Derived | A content pane's delta over the body |
| `--color-inset` | `bg-inset` | Text at 3% | A well inside a section: a grouped list, a read-only field |
| `--video-ground` | `bg-video-ground` | `0.13` in both | The letterbox behind video. Dark in both themes, because it frames a picture |

Set the covers and leave the coats alone: they're computed so each region composites to exactly its cover. See [The ground and the coats](/docs/concepts/design-language#the-ground-and-the-coats).

### Floats

| Token | Utility | Dark | Light |
| --- | --- | --- | --- |
| `--glass-float` | `glass-float` | The dialog tier plus 3% white, about `#1D1D1D` | `0.99` |
| `--glass-float-dialog` | `glass-float-dialog` | The solid plus 6% white, about `#161616` | `0.99` |
| `--glass-float-tooltip` | `glass-float-tooltip` | The solid | `0.99` |
| `--glass-float-rim` |  | White 10% | Black 10% |
| `--glass-float-drop` |  | `0 14px 44px` black 50%, `0 1px 3px` black 30% | `0 12px 36px` black 14%, `0 1px 3px` black 8% |
| `--glass-float-dialog-drop` |  | The same as `--glass-float-drop` | `0 16px 48px` black 20%, `0 1px 10px` black 14% |

A light dialog gets the deeper drop so porcelain separates from the white chrome under it.

### Text tiers

| Token | Utility | Dark · light | Increase Contrast |
| --- | --- | --- | --- |
| `--foreground` | `text-foreground` | 0.97 · 0.17 | Unchanged |
| `--muted-foreground` | `text-muted-foreground` | 0.71 · 0.47 | 0.8 · 0.38 |
| `--subtle` | `text-subtle` | 0.62 · 0.54 | 0.68 · 0.45 |

### Semantic tones

| Token | Dark | Light | Use |
| --- | --- | --- | --- |
| `--live` | `oklch(0.62 0.24 27)` | `oklch(0.55 0.24 27)` | Record, on air |
| `--destructive` | `oklch(0.6 0.23 27)` | `oklch(0.55 0.24 27)` | Failed, delete |
| `--success` | `oklch(0.7 0.15 150)` | `oklch(0.6 0.14 150)` | Healthy, connected |
| `--warning` | `oklch(0.81 0.15 75)` | `oklch(0.75 0.15 75)` | Needs attention |
| `--info` | `oklch(0.68 0.14 250)` | `oklch(0.58 0.14 250)` | Neutral news, rarely |
| `--member` | `oklch(0.7 0.12 300)` | `oklch(0.55 0.13 300)` | Paid membership. Only a member row's edge, never text |
| `--reward` | `oklch(0.72 0.11 200)` | `oklch(0.55 0.11 200)` | Channel point rewards. Only a row tint, never text |

Each has a `-foreground` partner except `--reward`, and each maps to Tailwind colors (`bg-success`, `bg-live/10`). Show a status through a [tone utility](#utilities) on a chip or a dot rather than coloring text.

The theme also carries theme-invariant brand tints for platform marks (`text-platform-youtube`, `-twitch`, `-instagram`, `-facebook`, `-kick`), and meter and channel tones (`--meter-ok`, `--meter-warn`, `--meter-clip`, `--channel-mute`) for audio components.

### Hairlines and selection

| Token | Utility | Dark · light | Increase Contrast |
| --- | --- | --- | --- |
| `--border` | `border-border` | White 10% · black 12% | 24% · 28% |
| `--input` | `border-input` | White 10% · black 12% | 24% · 28% |
| `--ring` | `ring-ring` | White 28% · black 25% | Unchanged |
| `--accent` | `bg-accent` | White 8% · black 6% | Unchanged |
| `--accent-pressed` | `bg-accent-pressed` | White 12% · black 10% | Unchanged |

A hairline is always 1 px. `bg-accent` is the hover and selected block for rows and menu items: a full-row fill, no outline.

shadcn's own tokens (`--background`, `--card`, `--primary`, `--secondary`, `--muted`, `--popover`, `--sidebar-*`) are all set, monochrome. `--primary` is ink on porcelain and chrome on black, and `--popover` follows `--glass-float`.

### Radius

| Utility         | Token            | Size  | For                      |
| --------------- | ---------------- | ----- | ------------------------ |
| `rounded-panel` | `--radius-panel` | 12 px | Containers, dialogs      |
| `rounded-row`   | `--radius-row`   | 8 px  | Rows, cards, tooltips    |
| `rounded-chip`  | `--radius-chip`  | 6 px  | Controls, key chips      |
| `rounded-tag`   | `--radius-tag`   | 7 px  | Tags                     |
| `rounded-lg`    | `--radius-lg`    | 10 px | Menus, selects, popovers |

`--radius` is `0.625rem`, and shadcn's `rounded-sm` to `rounded-xl` scale stays on it for stock components. Videorc's own code uses the tiers.

### Desktop scale

| Utility                     | Token                   | Size  |
| --------------------------- | ----------------------- | ----- |
| `h-control`, `size-control` | `--spacing-control`     | 28 px |
| `h-row`                     | `--spacing-row`         | 32 px |
| `h-row-compact`             | `--spacing-row-compact` | 28 px |
| `h-toolbar`                 | `--spacing-toolbar`     | 40 px |
| `h-status-bar`              | `--spacing-status-bar`  | 26 px |
| `px-gutter`                 | `--spacing-gutter`      | 16 px |

They're spacing tokens, so every spacing utility takes them: `min-h-row`, `gap-gutter`, `py-gutter`. See [Desktop scale](/docs/concepts/desktop-scale).

### Type

| Utility        | Size  | Line height | Weight  |
| -------------- | ----- | ----------- | ------- |
| `text-label`   | 11 px | 16 px       | 600     |
| `text-meta`    | 12 px | 16 px       | Regular |
| `text-section` | 13 px | 20 px       | 600     |

Body text stays `text-sm` (14 px).

### Chip and chrome tokens

The `--chip-*`, `--keycap-*`, `--chrome-*`, `--chrome-row-*`, `--knob*` and `--scrollbar-thumb*` tokens tune the utilities below: fills, rims, highlights, drops and gradient stops, per theme. Tune the tokens, not the utilities.

## Utilities

| Utility | What it paints |
| --- | --- |
| `glass-chip` | A neutral chip: a gradient fill, rim, top highlight and soft drop |
| `glass-chip-tinted` | An emphasis chip: the same glass tinted with `--chip-tone`, with tone-mixed text |
| `glass-dot` | A status dot in `--chip-tone`, with a 2 px halo and a glow |
| `glass-keycap` | A key chip: a brighter top edge and a dark bottom edge |
| `glass-float` | The popup tier: menus, selects, popovers, hover cards, toasts |
| `glass-float-dialog` | The dialog tier: dialogs and the command palette |
| `glass-float-tooltip` | The tooltip tier |
| `chrome-fill` | The polished primary fill. Lifts on hover, turns concave when pressed, flat when disabled |
| `chrome-plate` | The selected or active plate |
| `chrome-bead` | A knob or thumb: a silver bead in dark, a pearl in light |
| `chrome-bead-ink` | The dark bead for a knob on a chrome track |
| `chrome-led` | Record's metallic red. Lights and glows with `data-lit` |
| `chrome-row-live` | A row that's on stream: a plate with a polished 2 px edge on the left |
| `chrome-row-member` | A member's row: a quieter plate with a 2 px edge in the member hue |
| `tone-success`, `tone-warning`, `tone-destructive`, `tone-live`, `tone-info` | Set `--chip-tone` for the chip and dot utilities |
| `tone-neutral` | A gray tone whose dot doesn't glow |

Pair a `glass-*` utility with `border`: it sets the rim's color, and the element brings the width. The `chrome-*` utilities write their light and shade into Tailwind's shadow stack, so focus rings still compose with them.

## Toasts

The theme restyles [Sonner](/docs/components/sonner): every toast is the same `glass-float` panel with monochrome text, and a typed toast colors its icon only. `richColors` would paint solid green, amber and red panels; here its colors point back at the glass.

## Accessibility

The theme follows three system settings. They're media queries, so a change applies at once, with no reload.

| Setting | What changes |
| --- | --- |
| `prefers-contrast: more` | Hairlines, input borders and every rim get stronger. The secondary and tertiary text tiers move a step closer to primary. Both covers go to 95%. A chrome fill and Record gain a 1 px edge |
| `prefers-reduced-transparency: reduce` | The window coat becomes `--glass-solid`, and the sidebar and content coats go transparent, so text contrast never depends on what's behind it. It wins when Increase Contrast is on too |
| `prefers-reduced-motion: reduce` | Every animation and transition collapses to 0.01 ms with one iteration, and `scroll-behavior` goes to `auto`. Behavior stays the same |

Under both contrast settings, the chrome controls keep their gradients: they're opaque.

## Customizing

The components read the variables, so customizing is editing them in your global stylesheet:

- Change a cover (`--glass-cover-sidebar`, `--glass-cover-work`), not a coat. The coats are derived from the covers.
- After changing a surface or a text color, check the contrast of all three text tiers over your own background.
- Keep neutrals at chroma 0 to keep the monochrome look.

Running `npx shadcn@latest add @videorc/theme` again merges the registry's values back over your edits.

In this repository the theme is generated. `styles/videorc.css` is the source of truth, comments and all, and `pnpm theme:build` turns it into the registry's `theme` item. Edit the stylesheet, then run the build; `pnpm theme:check` fails while the registry is out of date.

## On a web page

The coats are translucent and composite to the theme's solid. On a web page, give the page that solid so they come out the tone Videorc shows:

```css title="app/globals.css"
@layer base {
  html {
    background-color: var(--glass-solid);
  }
}
```

Leave out the [desktop base](/docs/concepts/desktop) on a website, so text stays selectable.

# Accelerator (/docs/hooks/accelerator)

## Installation

```npm
npx shadcn@latest add @videorc/accelerator
```

## Usage

```tsx
import {
  acceleratorAriaKeyShortcuts,
  acceleratorLabel,
} from "@/lib/accelerator";
```

```tsx
acceleratorLabel("CmdOrCtrl+Shift+J", "darwin"); // "⇧⌘J"
acceleratorLabel("CmdOrCtrl+Shift+J", "win32"); // "Ctrl+Shift+J"
acceleratorAriaKeyShortcuts("CmdOrCtrl+K", "darwin"); // "Meta+K"
```

Every function takes the platform explicitly, as Node's `process.platform` names it (`"darwin"`, `"win32"`, `"linux"`). It's pure, with no DOM and no React, so main, preload and the renderer can all share it.

In components, reach for [ShortcutKeys](/docs/components/shortcut-keys), which draws the key chip, or for `shortcutLabel` from [platform](/docs/hooks/platform), which fills in the platform for you.

## How shortcuts read

| Accelerator            | macOS | Windows and Linux |
| ---------------------- | ----- | ----------------- |
| `CmdOrCtrl+K`          | ⌘K    | Ctrl+K            |
| `CmdOrCtrl+Shift+J`    | ⇧⌘J   | Ctrl+Shift+J      |
| `Shift+CmdOrCtrl+N`    | ⇧⌘N   | Ctrl+Shift+N      |
| `Ctrl+Alt+Shift+Cmd+R` | ⌃⌥⇧⌘R | Ctrl+Alt+Shift+R  |
| `CmdOrCtrl+Enter`      | ⌘↵    | Ctrl+Enter        |
| `Shift+Backspace`      | ⇧⌫    | Shift+Backspace   |
| `Delete`               | ⌦     | Delete            |
| `Escape`               | Esc   | Esc               |
| `Space`                | Space | Space             |
| `Super+F13`            | ⌘F13  | Win+F13           |
| `Alt`                  | ⌥     | Alt               |

## Behavior

- **One notation per platform.** On macOS: glyphs in the system's order (⌃⌥⇧⌘) with no separator, as macOS menus print them. On Windows and Linux: words in Ctrl, Alt, Shift, Win order, joined by "+", and never a Mac glyph. The order you write the accelerator in doesn't matter.
- **Every Electron spelling reads,** in any case: `Command`, `Cmd`, `CommandOrControl`, `CmdOrCtrl`, `Control`, `Ctrl`, `Alt`, `Option`, `AltGr`, `Shift`, `Super` and `Meta`. `Return` reads as Enter and `Esc` as Escape, letters are uppercased, and `f5` becomes F5.
- **`CmdOrCtrl` is ⌘ on macOS and Ctrl elsewhere.** `Command` reads as Ctrl off macOS too: Electron ignores it there, so Ctrl is what it has always meant. `Super` and `Meta` are ⌘ on macOS and Win elsewhere.
- **One saved spelling.** `parseAccelerator` returns modifiers in a fixed order (Cmd, Ctrl, Alt, Shift, Super), so one binding always has one spelling, which keeps duplicate checks and diffs honest.
- **Exactly one key.** A value with no key, or with two (`Cmd+A+B`), doesn't parse: `parseAccelerator` returns `null`, and `acceleratorLabel` prints the value unchanged. An empty or missing value prints `""`.
- **A modifier alone** (`Shift`, `Alt`) prints as a hint for a drag, such as "⇧ constrains".
- **`aria-keyshortcuts` names the real keys,** in UI Events names: Meta on macOS and Control elsewhere, `ArrowUp` for Up. Modifiers come in Control, Alt, Shift, Meta order.
- **No platform reads as Windows and Linux.** Passing `undefined` prints Ctrl. Use [platform](/docs/hooks/platform) to fill in the current one.
- **`commandModifierHeld`** is true for ⌘ alone on macOS and Ctrl alone elsewhere, so an app shortcut on ⌘K leaves ⌃K to text editing on a Mac. It takes Electron's `Input` (`meta`, `control`); map a DOM event's `metaKey` and `ctrlKey` onto it, or use `isCommandKey` from [platform](/docs/hooks/platform).

## API reference

| Export | Signature | Returns |
| --- | --- | --- |
| `acceleratorLabel` | `(accelerator: string \| undefined, platform: string \| undefined) => string` | The shortcut as one string: "⇧⌘J", "Ctrl+Shift+J" |
| `acceleratorDisplayKeys` | `(accelerator: string \| undefined, platform: string \| undefined) => string[]` | Its parts in display order: `["⇧", "⌘", "J"]`, `["Ctrl", "Shift", "J"]` |
| `acceleratorAriaKeyShortcuts` | `(accelerator: string \| undefined, platform: string \| undefined) => string` | The `aria-keyshortcuts` value, or `""` when nothing parses |
| `acceleratorModifiersLabel` | `(modifiers: readonly AcceleratorModifier[], platform: string \| undefined) => string` | Modifiers held mid-press, with no key yet: "⇧⌘", "Ctrl+Shift" |
| `acceleratorModifierLabels` | `(modifiers: readonly AcceleratorModifier[], platform: string \| undefined) => string[]` | The same, as separate labels |
| `parseAccelerator` | `(value: string \| undefined, platform: string \| undefined) => ParsedAccelerator \| null` | The modifiers and the key, or `null` |
| `commandModifierHeld` | `(input: { meta: boolean; control: boolean }, platform: string \| undefined) => boolean` | Whether the platform's command modifier is down |
| `MODIFIER_ORDER` | `readonly AcceleratorModifier[]` | The saved order: Cmd, Ctrl, Alt, Shift, Super |

```ts
type AcceleratorModifier = "Cmd" | "Ctrl" | "Alt" | "Shift" | "Super";

interface ParsedAccelerator {
  modifiers: AcceleratorModifier[];
  key: string;
}
```

# Hooks and libs (/docs/hooks)

These are plain TypeScript, with no Next.js and no Electron in them. The libs are pure functions you can call anywhere, including Electron's main process; the hooks need React. Components install the ones they use, and you can install any of them on its own.

| Item | Path | What it does |
| --- | --- | --- |
| [Accelerator](/docs/hooks/accelerator) | `lib/accelerator.ts` | Parses Electron accelerators and prints them per platform: ⇧⌘J on macOS, Ctrl+Shift+J elsewhere |
| [Platform](/docs/hooks/platform) | `lib/platform.ts` | Works out the platform, and gives shortcut labels and OS words such as Finder and Trash |
| [Modal open](/docs/hooks/modal-open) | `lib/modal-open.ts` | Tells a global key whether a dialog, menu or select is open, so it doesn't fire from under one |
| [useThemeToggle](/docs/hooks/use-theme-toggle) | `hooks/use-theme-toggle.ts` | Toggles light and dark with a button and the D key, handing back to System when it can |
| [useReducedMotion](/docs/hooks/use-reduced-motion) | `hooks/use-reduced-motion.ts` | True when the system asks to reduce motion, plus a scroll behavior that respects it |
| [Status word](/docs/hooks/status-word) | `lib/status-word.ts` | The status tones and their chip utilities, and the guard that a status says a word, never a raw value |

# Modal open (/docs/hooks/modal-open)

## Installation

```npm
npx shadcn@latest add @videorc/modal-open
```

## Usage

```tsx
import { isModalOpen } from "@/lib/modal-open";
```

Ask it first in every global key handler. Here Space starts and stops a recording, but not from under a dialog or a menu, and not from a control that uses Space itself:

```tsx
useEffect(() => {
  const onKeyDown = (event: KeyboardEvent) => {
    if (event.code !== "Space" || event.repeat || isModalOpen()) {
      return;
    }
    const usesSpace =
      event.target instanceof Element &&
      event.target.closest(
        "button, input, textarea, select, [contenteditable]"
      );
    if (usesSpace) {
      return;
    }
    event.preventDefault();
    toggleRecording();
  };
  document.addEventListener("keydown", onKeyDown);
  return () => document.removeEventListener("keydown", onKeyDown);
}, [toggleRecording]);
```

[useThemeToggle](/docs/hooks/use-theme-toggle) does the same for its D key.

## Behavior

- **It reads the page, not React state,** so it sees a popup from any component, including one rendered in a portal.
- **It matches four roles with Base UI's `data-open`:** `dialog`, `alertdialog`, `menu` and `listbox`. Base UI gives an open dialog, alert dialog, popover, menu or context menu its role and `data-open`, so all of them count.
- **Only open popups count.** Base UI removes `data-open` as a popup starts to close, so a dialog on its way out no longer blocks keys. A listbox that's part of the page, with no `data-open`, never counts.
- **It checks `document` by default.** Pass another root to look inside a shadow root, another document or a test container. Call it from an event handler or an effect: on a server there's no `document`.
- `MODAL_OPEN_SELECTOR` is the same check as a selector, for CSS or tests.

## API reference

| Export | Signature | Returns |
| --- | --- | --- |
| `isModalOpen` | `(root?: Pick<Document, "querySelector">) => boolean` | True while a dialog, an alert, a menu or a select is open under `root` (default `document`) |
| `MODAL_OPEN_SELECTOR` | `string` | `[role="dialog"][data-open], [role="alertdialog"][data-open], [role="menu"][data-open], [role="listbox"][data-open]` |

# Platform (/docs/hooks/platform)

## Installation

```npm
npx shadcn@latest add @videorc/platform
```

It brings [Accelerator](/docs/hooks/accelerator) with it.

## Usage

```tsx
import {
  revealInFileManagerLabel,
  shortcutLabel,
  trashName,
} from "@/lib/platform";
```

```tsx
shortcutLabel("CmdOrCtrl+K"); // "⌘K" on a Mac, "Ctrl+K" elsewhere
revealInFileManagerLabel(platform); // "Show in Finder", "Show in Explorer" or "Show in folder"
trashName(platform); // "Trash" or "Recycle Bin"
```

```tsx
<DropdownMenuItem onClick={reveal}>
  {revealInFileManagerLabel(platform)}
</DropdownMenuItem>
```

Never type a platform word or a key glyph into copy. "Show in Finder" is wrong on Windows, and "⌘K" is wrong everywhere but macOS.

## Where the platform comes from

`currentPlatform()` decides, in this order:

1. **The platform you pass,** with Node's `process.platform` names: `"darwin"`, `"win32"`, `"linux"`. In Electron, your app knows it for certain; pass it when you have it.
2. **`data-platform` on `<html>`,** set by a small script before the first paint, so a Mac never flashes "Ctrl". See [Using it in Electron](/docs/concepts/electron#platform-glyphs).
3. **The user agent:** "Windows" reads as `win32`, "Macintosh" as `darwin`, and anything else as `linux`.

Not every function falls back the same way:

| Function | With no platform passed |
| --- | --- |
| `shortcutLabel`, `shortcutAriaKeys`, `isCommandKey`, `displayKeyGlyph` | `currentPlatform()`: `data-platform`, then the user agent |
| `revealInFileManagerLabel`, `trashName` | The user agent only |
| `osSettingsName`, `appPlatform`, `isMacPlatform`, `isWindowsPlatform` | No fallback: a missing platform reads as Linux and other systems |

Pass the platform everywhere you can, and every label agrees.

## Behavior

- **Shortcuts read like the platform's menus:** one keycap in system order on macOS (⇧⌘J, ⌘↵), words joined by "+" elsewhere (Ctrl+Shift+J, Ctrl+Enter). [Accelerator](/docs/hooks/accelerator) does the printing.
- **`isCommandKey` takes ⌘ alone on macOS** and Ctrl alone elsewhere, never the Windows key. On a Mac, ⌃K and ⌃P stay text editing.
- **`displayKeyGlyph` translates one Mac glyph** for the platform: ⌘ to Ctrl, ⌥ to Alt, ⇧ to Shift. It's for a lone modifier; print whole shortcuts from accelerators.
- **Linux is "other".** `appPlatform` sorts every platform into `"darwin"`, `"win32"` or `"other"`, and the OS words use their generic form there: "Show in folder", "system settings".
- **Server rendering.** On a server there's no `data-platform`, and Node's own `navigator` reads as Linux, so a label rendered there says "Ctrl+K". If you render on a server, pass the platform, or render shortcut labels on the client only.

## API reference

| Export | Signature | Returns |
| --- | --- | --- |
| `currentPlatform` | `(platform?: string) => string \| undefined` | The platform passed, else `data-platform`, else the user agent's |
| `shortcutLabel` | `(accelerator: string, platform?: string) => string` | "⇧⌘J" on macOS, "Ctrl+Shift+J" elsewhere |
| `shortcutAriaKeys` | `(accelerator: string, platform?: string) => string` | The `aria-keyshortcuts` value: "Meta+K", "Control+K" |
| `isCommandKey` | `(event: { metaKey: boolean; ctrlKey: boolean }, platform?: string) => boolean` | Whether the app's command modifier is down |
| `displayKeyGlyph` | `(glyph: string, platform: string \| undefined) => string` | One Mac glyph, translated for the platform |
| `revealInFileManagerLabel` | `(platform?: string) => string` | "Show in Finder", "Show in Explorer" or "Show in folder" |
| `trashName` | `(platform?: string) => string` | "Trash" or "Recycle Bin" |
| `osSettingsName` | `(platform: string \| undefined) => string` | "System Settings", "Windows Settings" or "system settings" |
| `appPlatform` | `(platform: string \| undefined) => AppPlatform` | `"darwin"`, `"win32"` or `"other"` |
| `isMacPlatform` | `(platform: string \| undefined) => boolean` | True for `"darwin"` |
| `isWindowsPlatform` | `(platform: string \| undefined) => boolean` | True for `"win32"` |

```ts
type AppPlatform = "darwin" | "win32" | "other";
```

# Status word (/docs/hooks/status-word)

## Installation

```npm
npx shadcn@latest add @videorc/status-word
```

## Usage

```tsx
import {
  assertStatusWord,
  STATUS_TONE_CLASS,
  statusWordFromValue,
} from "@/lib/status-word";
import type { StatusTone } from "@/lib/status-word";
```

```tsx
const TONE: Record<ConnectionState, StatusTone> = {
  connected: "good",
  reconnecting: "warn",
  failed: "error",
};

<span className={STATUS_TONE_CLASS[TONE[state]]}>…</span>;
```

## Tones

A tone says what a status means, never how it looks. `STATUS_TONE_CLASS` maps each one to the `tone-*` utility that sets `--chip-tone`.

| Tone      | Means                              | Utility            |
| --------- | ---------------------------------- | ------------------ |
| `good`    | It works                           | `tone-success`     |
| `warn`    | It's degraded, or can't happen now | `tone-warning`     |
| `error`   | It failed and needs you            | `tone-destructive` |
| `live`    | Recording or on air                | `tone-live`        |
| `neutral` | Idle                               | `tone-neutral`     |

## Words, not values

A status chip or dot says a word in sentence case ("Needs permission"), never a machine value ("permission-needed"). Map every state to its word where the state lives; don't recase it in the component.

- `isRawStatusValue(text)` is true for a lower-case, hyphenated value such as `device-missing`. Words, numbers and units pass.
- `statusWordFromValue(value)` is the last resort for a state no map names yet: `device-missing` reads "Device missing".
- `assertStatusWord(text, component)` reports a raw value that reached a status primitive. Under test (`NODE_ENV` is `test`) it throws, so a leak fails CI; a development build logs it; a production build says nothing. Status Badge and Status Dot call it on every render.

# useReducedMotion (/docs/hooks/use-reduced-motion)

## Installation

```npm
npx shadcn@latest add @videorc/use-reduced-motion
```

## Usage

```tsx
import {
  smoothScrollBehavior,
  useReducedMotion,
} from "@/hooks/use-reduced-motion";
```

Use the hook for motion CSS can't see, such as a JavaScript animation or a canvas:

```tsx
function LevelMeter({ level }: { level: number }) {
  const reducedMotion = useReducedMotion();
  return reducedMotion ? (
    <StaticLevel level={level} />
  ) : (
    <AnimatedLevel level={level} />
  );
}
```

Pass `smoothScrollBehavior()` instead of a bare `"smooth"` to a script-driven scroll:

```tsx
row.scrollIntoView({ behavior: smoothScrollBehavior(), block: "nearest" });
```

## Behavior

- **CSS motion doesn't need it.** The [theme](/docs/concepts/theme#accessibility) already collapses every CSS transition and animation, and `scroll-behavior`, under reduced motion. The hook and the helper cover what runs in JavaScript.
- **It follows the setting live.** The hook subscribes to `(prefers-reduced-motion: reduce)` and re-renders when it changes, with no reload.
- **It's `false` on the server,** and during hydration, then the real value right after.
- **`smoothScrollBehavior()` isn't a hook.** It reads the setting when you call it, so call it in the event handler or effect that scrolls. It returns `"auto"` under reduced motion and `"smooth"` otherwise, including on a server.
- **It shares a path with audiocn's hook.** audiocn ships `hooks/use-reduced-motion.ts` with the same `useReducedMotion`; this file adds `smoothScrollBehavior`. If you use both registries and the CLI asks to overwrite this file with audiocn's, keep this one.

## API reference

| Export | Signature | Returns |
| --- | --- | --- |
| `useReducedMotion` | `() => boolean` | True when the system asks to reduce motion |
| `smoothScrollBehavior` | `() => ScrollBehavior` | `"auto"` under reduced motion, else `"smooth"` |

# useThemeToggle (/docs/hooks/use-theme-toggle)

## Installation

```npm
npx shadcn@latest add @videorc/use-theme-toggle
```

It adds `hooks/use-theme-toggle.ts` and `lib/theme-choice.ts`, and brings [Modal open](/docs/hooks/modal-open) and `next-themes` with it.

## Usage

The hook runs on [next-themes](https://github.com/pacocoursey/next-themes), which works outside Next.js too, in a Vite or Electron renderer. Wrap your app in its provider with `attribute="class"`, so the theme's `.dark` column follows:

```tsx
import { ThemeProvider } from "next-themes";
import type { ReactNode } from "react";

export function Providers({ children }: { children: ReactNode }) {
  return (
    <ThemeProvider
      attribute="class"
      defaultTheme="system"
      disableTransitionOnChange
    >
      {children}
    </ThemeProvider>
  );
}
```

Then call the hook in the component that owns the toggle:

```tsx
import { DarkModeIcon, LightModeIcon } from "@/components/icons";
import { Button } from "@/components/ui/button";
import { useThemeToggle } from "@/hooks/use-theme-toggle";

export function ThemeButton() {
  const { toggleTheme } = useThemeToggle();
  return (
    <Button
      aria-keyshortcuts="D"
      aria-label="Toggle theme"
      onClick={toggleTheme}
      size="icon"
      variant="ghost"
    >
      <LightModeIcon className="dark:hidden" />
      <DarkModeIcon className="hidden dark:block" />
    </Button>
  );
}
```

## Behavior

- **Each press flips what the window shows,** light or dark.
- **It hands back to System when it can.** If the flip lands on the look the computer already asks for, it saves `"system"` instead of that theme. Flip away and back, and the app follows the computer again rather than pinning a theme for good.
- **The D key works while the hook is mounted.** It listens on the document and ignores the key:
  - on key repeat;
  - with ⌘, Ctrl or Alt held, so ⌘D and Ctrl+D stay with the app;
  - in an input, a textarea, a select or an editable element;
  - while a dialog, an alert, a menu or a select is open ([Modal open](/docs/hooks/modal-open)).
- **It matches the character.** Shift+D toggles too. On a keyboard layout where that key types another letter, it doesn't.
- **A handled D is consumed** with `preventDefault`.
- **Mount it once.** Two copies both answer the key, but they compute the same next theme, so it still flips once.

| The window shows | The computer asks for | The next choice |
| ---------------- | --------------------- | --------------- |
| Dark             | Dark                  | `"light"`       |
| Light            | Light                 | `"dark"`        |
| Light            | Dark                  | `"system"`      |
| Dark             | Light                 | `"system"`      |
| Dark             | Unknown               | `"light"`       |
| Unknown          | Unknown               | `"dark"`        |

## API reference

| Export | From | Signature |
| --- | --- | --- |
| `useThemeToggle` | `@/hooks/use-theme-toggle` | `() => { toggleTheme: () => void }` |
| `nextToggledTheme` | `@/lib/theme-choice` | `({ resolvedTheme, systemTheme }: { resolvedTheme: string \| undefined; systemTheme: string \| undefined }) => ThemeChoice` |

```ts
type ThemeChoice = "light" | "dark" | "system";
```

`resolvedTheme` is what the window shows now, and `systemTheme` is what the computer asks for: pass next-themes' values of the same names.

# Introduction (/docs)

videorc/ui is where Videorc's interface is designed and kept. Every button, menu, row and pane the desktop app draws starts here, and the app installs it with the same `shadcn` CLI you use.

It is a [shadcn registry](https://ui.shadcn.com/docs/registry): you get the source, in your project, and you own it.

## What's inside

| Section | What it is |
| --- | --- |
| [Concepts](/docs/concepts/design-language) | The design language: surfaces, glass chips, the three text tiers and the desktop scale |
| [Components](/docs/components) | shadcn/ui components rebuilt for Videorc on Base UI, plus Videorc's own: segmented controls, shortcut keys, disabled reasons |
| [Primitives](/docs/primitives) | The shared building blocks of every Videorc screen: grouped lists and rows, panes and toolbars, status bars, kebab menus, confirm dialogs |
| [Hooks and libs](/docs/hooks) | The small pieces the components share: platform glyphs, accelerators, reduced motion |

## Principles

- **Color is information.** The chrome is monochrome. Saturated color appears only in status (live, success, warning, destructive) and in source icons.
- **A desktop app, not a page.** Controls are desktop-sized (28 px), rows are 32 px, toolbars 40 px. Every primary action has a keyboard shortcut.
- **One primitive per job.** A list of like things is a `GroupedList` of `ListRow`s, a confirmation is a `ConfirmDialog`, a shortcut is `ShortcutKeys`. Screens compose primitives; they don't restyle them.
- **Dark first, light as its twin.** Dark is the reference; light is the same structure in porcelain and graphite.

## For AI agents

Every component and primitive page has a **Copy prompt for AI** button, and every page is available as Markdown by appending `.md` to its URL. [llms.txt](/llms.txt) indexes every page.

# Installation (/docs/installation)

videorc/ui is a [shadcn registry](https://ui.shadcn.com/docs/registry). You add components with the `shadcn` CLI, and the code lands in your project.

## Requirements

- React 19.2 or later and Tailwind CSS v4.
- A shadcn/ui project on Base UI (a `base-*` style). The components import `@base-ui/react`.
- `shadcn/tailwind.css` imported in your global stylesheet, after `tailwindcss`. It defines the `data-open`, `data-checked`, `data-horizontal` and other variants the components style with. Every `base-*` project has it.

### Set up shadcn/ui

Skip this if your project already has a `components.json`.

### Add the registry

Add the `@videorc` namespace to `components.json`:

```json title="components.json"
{
  "registries": {
    "@videorc": "https://ui.videorc.com/r/{name}.json"
  }
}
```

### Add the theme

```npm
npx shadcn@latest add @videorc/theme
```

This merges the Videorc tokens, utilities and base layer into your global stylesheet. Every component depends on it, so the CLI also adds it with the first component you install.

For a desktop app (Electron, Tauri), also add `@videorc/desktop`: chrome text stops selecting, the arrow stays the pointer, and the window stops rubber-banding.

### Add a component

## What gets installed

| Path | What it is |
| --- | --- |
| `components/ui/*` | Components, one file each |
| `components/*` | Primitives: rows, panes, status bars, menus |
| `components/icons.tsx` | The semantic icon set every component draws from |
| `hooks/*`, `lib/*` | The shared hooks and helpers |
| Your global CSS | The theme: tokens in light and dark, `@theme` mappings, utilities, base layer |

Paths follow the aliases in your `components.json`, so they adapt to a `src/` folder or custom aliases.

## The ground

Videorc's surfaces are translucent coats, tuned to sit on a window's solid tone. On a plain page, give the page the theme's solid so the coats composite to the right tone:

```css title="app/globals.css"
@layer base {
  html {
    background-color: var(--glass-solid);
  }
}
```

## For AI agents

Every page has a **Copy prompt for AI** button that copies the install steps, usage, examples and API as one document. The same document is served at the page URL with `.md` appended:

```bash
curl https://ui.videorc.com/docs/components/button.md
```

[llms.txt](/llms.txt) indexes every page, and [llms-full.txt](/llms-full.txt) is the whole documentation in one file.

# Confirm Dialog (/docs/primitives/confirm-dialog)

```tsx title="components/examples/confirm-dialog-demo.tsx"
"use client";

import { useState } from "react";

import { ConfirmDialog } from "@/components/confirm-dialog";
import { Button } from "@/components/ui/button";

const DELETE_TAKES_MS = 1500;

const ConfirmDialogDemo = () => {
  const [open, setOpen] = useState(false);
  const [deleting, setDeleting] = useState(false);

  // The dialog stays up, saying "Deleting…", until the work is done: then
  // the owner closes it.
  const confirm = () => {
    setDeleting(true);
    setTimeout(() => {
      setDeleting(false);
      setOpen(false);
    }, DELETE_TAKES_MS);
  };

  return (
    <>
      <Button onClick={() => setOpen(true)} variant="destructive">
        Delete saved scene…
      </Button>
      <ConfirmDialog
        cancelDisabled={deleting}
        confirmDisabled={deleting}
        confirmLabel={deleting ? "Deleting…" : "Delete scene"}
        description="Only the saved snapshot is deleted. Your current scene and recording continue."
        onCancel={() => {
          if (!deleting) {
            setOpen(false);
          }
        }}
        onConfirm={confirm}
        open={open}
        title="Delete saved scene?"
      />
    </>
  );
};

export default ConfirmDialogDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/confirm-dialog
```

## Usage

```tsx
import { ConfirmDialog } from "@/components/confirm-dialog";
```

```tsx
<ConfirmDialog
  confirmLabel="Delete scene"
  description="Only the saved snapshot is deleted. Your current scene and recording continue."
  onCancel={() => setOpen(false)}
  onConfirm={deleteScene}
  open={open}
  title="Delete saved scene?"
/>
```

## Confirm and undo

Every destructive action either asks first or can be undone.

- **Confirm** with `ConfirmDialog` when the loss is real and hard to restore:
  - the title is "Verb object?": "Delete saved scene?";
  - one sentence names exactly what is lost;
  - the safe answer ("Cancel", or "Keep …") is a ghost button with focus on open, and Escape is the same answer;
  - the destructive button reads verb + object: "Delete scene";
  - there's no close button: the two answers are the only way out.
- **Undo** a frequent, cheap-to-restore action instead of asking: run it after a short window unless it's undone, with an Undo action on its [toast](/docs/components/sonner). Asking every time trains people to click through the question.

The dialog is controlled, and the owner closes it by dropping `open`: at once after a synchronous action, or once an async one settles. Meanwhile `confirmLabel` says "Deleting…" and `confirmDisabled` keeps it from running twice, as in the demo above.

Use it for deletes and anything else that destroys work. Don't use it for a question that isn't a destructive confirmation, or for a cheap action that can be undone.

## Examples

### A replace that destroys nothing

A consequential step that destroys nothing, such as replacing what's been typed, passes `confirmVariant="default"`, so the answer is the chrome fill instead of the destructive tint. The safe answer can name what it keeps.

```tsx title="components/examples/confirm-dialog-replace.tsx"
"use client";

import { useState } from "react";

import { ConfirmDialog } from "@/components/confirm-dialog";
import { Button } from "@/components/ui/button";

const ConfirmDialogReplace = () => {
  const [open, setOpen] = useState(false);
  return (
    <>
      <Button onClick={() => setOpen(true)} variant="secondary">
        Use for Go Live…
      </Button>
      <ConfirmDialog
        cancelLabel="Keep current details"
        confirmLabel="Replace details"
        confirmVariant="default"
        description="The title, description and privacy from this event replace what you've typed in Livestream → Setup."
        onCancel={() => setOpen(false)}
        onConfirm={() => setOpen(false)}
        open={open}
        title="Replace stream details?"
      />
    </>
  );
};

export default ConfirmDialogReplace;
```

## Theming

It's [Alert Dialog](/docs/components/alert-dialog) underneath: the dialog tier of the float glass, the panel radius and no backdrop blur.

| Token or attribute | Meaning |
| --- | --- |
| `Button` `ghost` | The safe answer |
| `Button` `destructive` or `default` | The answer, by `confirmVariant` |
| `data-testid` | `{testId}-dialog`, `{testId}-cancel` and `{testId}-confirm` |

## Keyboard

| Key | Action |
| --- | --- |
| <kbd>Esc</kbd> | Cancels: the same answer as the safe button |
| <kbd>Tab</kbd> | Moves between the answers; focus stays inside |
| <kbd>Enter</kbd> <kbd>Space</kbd> | Presses the focused answer, which starts on the safe one |

## Accessibility

The dialog is an `alertdialog`, named by its title and described by its sentence. The safe answer has focus on open, so a stray <kbd>Enter</kbd> never destroys anything. A click outside doesn't close it.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | — | — |
| `title` | `ReactNode` | — | "Verb object?" |
| `description` | `ReactNode` | — | One sentence naming exactly what is lost. |
| `confirmLabel` | `ReactNode` | — | Verb + object, or "Deleting…" while it runs. |
| `cancelLabel` | `ReactNode` | `"Cancel"` | The safe answer: "Cancel", or "Keep …". |
| `confirmVariant` | `"destructive" \| "default"` | `"destructive"` | default for a step that destroys nothing. |
| `confirmDisabled` | `boolean` | `false` | — |
| `cancelDisabled` | `boolean` | `false` | — |
| `children` | `ReactNode` | — | Extra body between the sentence and the answers: an Alert, a field. |
| `testId` | `string` | — | Adds -dialog, -cancel and -confirm test ids. |
| `onCancel` | `() => void` | — | The safe button and Escape. |
| `onConfirm` | `() => void` | — | The answer. The dialog stays open until you drop open. |

# Device Picker (/docs/primitives/device-picker)

```tsx title="components/examples/device-picker-demo.tsx"
"use client";

import { useEffect, useState } from "react";

import { DevicePicker } from "@/components/device-picker";
import type { PickerDevice } from "@/components/device-picker";
import { Button } from "@/components/ui/button";

const DISCOVERY_TAKES_MS = 1500;

const CAMERAS: PickerDevice[] = [
  {
    id: "facetime",
    kind: "camera",
    name: "FaceTime HD Camera",
    status: "available",
  },
  { id: "desk", kind: "camera", name: "Desk Camera", status: "available" },
  {
    id: "cam-link",
    kind: "camera",
    name: "Cam Link 4K",
    status: "permission-required",
  },
];

const MICROPHONES: PickerDevice[] = [
  {
    id: "built-in",
    kind: "microphone",
    name: "MacBook Pro Microphone",
    status: "available",
  },
  { id: "shure", kind: "microphone", name: "Shure MV7", status: "available" },
  {
    id: "airpods",
    kind: "microphone",
    name: "AirPods Pro",
    status: "unavailable",
  },
];

const DevicePickerDemo = () => {
  const [pending, setPending] = useState(true);
  const [cameraId, setCameraId] = useState<string | undefined>("facetime");
  const [microphoneId, setMicrophoneId] = useState<string | undefined>();

  // Discovery reports after a moment, as it does when a window opens.
  useEffect(() => {
    if (!pending) {
      return;
    }
    const timer = setTimeout(() => setPending(false), DISCOVERY_TAKES_MS);
    return () => clearTimeout(timer);
  }, [pending]);

  return (
    <div className="flex w-full max-w-xs flex-col gap-4">
      <DevicePicker
        devices={pending ? [] : CAMERAS}
        discoveryPending={pending}
        kind="camera"
        label="Camera"
        noneLabel="Off"
        onChange={setCameraId}
        selectedName="FaceTime HD Camera"
        value={cameraId}
      />
      <DevicePicker
        devices={pending ? [] : MICROPHONES}
        discoveryPending={pending}
        kind="microphone"
        label="Microphone"
        noneLabel="Off"
        onChange={setMicrophoneId}
        value={microphoneId}
      />
      <Button
        className="self-start"
        disabled={pending}
        onClick={() => setPending(true)}
        size="xs"
        variant="secondary"
      >
        Find devices again
      </Button>
    </div>
  );
};

export default DevicePickerDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/device-picker
```

It installs `lib/source-select-state.ts`, the picker's words, beside the component.

## Usage

```tsx
import { DevicePicker } from "@/components/device-picker";
import type { PickerDevice } from "@/components/device-picker";
```

```tsx
<DevicePicker
  devices={cameras}
  discoveryPending={!camerasListed}
  kind="camera"
  label="Camera"
  noneLabel="Off"
  onChange={setCameraId}
  selectedName={savedCameraName}
  value={cameraId}
/>
```

A device is `{ id, name, kind, status, detail? }`. `status` is `"available"`, `"permission-required"` or `"unavailable"`; only an available device can be chosen, and the others say why in a muted word after their name. `onChange` gets the device id, or `undefined` for the "no device" item.

Use it everywhere a screen, window, camera or microphone is chosen, so they all say the same words. Don't use a [Select](/docs/components/select) for devices: it has no words for discovery, a missing device or a search.

## Words for every state

The picker never shows a blank surface. With nothing chosen, discovery and an empty list win over the "no device" words, so a missing camera never hides behind "Off".

| State | The trigger says | The list says |
| --- | --- | --- |
| Discovery hasn't reported | "Finding cameras…" | "Finding cameras…" |
| Nothing found | "No cameras found" | "No cameras found" |
| A device that can't run | Its name, then "Needs permission" or "Unavailable" | The same, disabled |
| A saved device that's gone | `selectedName` (or "Saved camera"), then "Not found" | The same, disabled |
| A search with no match |  | "No matching cameras" |

`kind` decides the nouns: `capture` for screens and windows, `camera`, or `microphone`. A saved device is only called "Not found" once discovery has reported.

## Examples

### Search, and screens and windows

`searchable` adds a search field that matches every word against a device's name, kind and `detail` (the app that owns a window), never its id. `groupByKind` puts screens and windows under their own headings when both are present.

```tsx title="components/examples/device-picker-search.tsx"
"use client";

import { useState } from "react";

import { DevicePicker } from "@/components/device-picker";
import type { PickerDevice } from "@/components/device-picker";

const SOURCES: PickerDevice[] = [
  {
    id: "display-1",
    kind: "screen",
    name: "Built-in Retina Display",
    status: "available",
  },
  {
    id: "display-2",
    kind: "screen",
    name: "Studio Display",
    status: "available",
  },
  {
    detail: "Safari",
    id: "safari-docs",
    kind: "window",
    name: "Videorc docs",
    status: "available",
  },
  {
    detail: "Keynote",
    id: "keynote",
    kind: "window",
    name: "Launch slides",
    status: "available",
  },
  {
    detail: "Notes",
    id: "notes",
    kind: "window",
    name: "Show notes",
    status: "permission-required",
  },
];

const DevicePickerSearch = () => {
  const [value, setValue] = useState<string | undefined>("display-1");
  return (
    <div className="w-full max-w-xs">
      <DevicePicker
        devices={SOURCES}
        groupByKind
        kind="capture"
        label="Screen or window"
        noneLabel="None"
        onChange={setValue}
        searchable
        value={value}
      />
    </div>
  );
};

export default DevicePickerSearch;
```

### Inline

`trigger="inline"` is a row's right-aligned value for a row whose label sits beside it. A long name truncates, and its title shows it whole.

```tsx title="components/examples/device-picker-inline.tsx"
"use client";

import { useState } from "react";

import { DevicePicker } from "@/components/device-picker";
import type { PickerDevice } from "@/components/device-picker";

const MICROPHONES: PickerDevice[] = [
  {
    id: "built-in",
    kind: "microphone",
    name: "MacBook Pro Microphone",
    status: "available",
  },
  { id: "shure", kind: "microphone", name: "Shure MV7", status: "available" },
];

const DevicePickerInline = () => {
  const [value, setValue] = useState<string | undefined>("usb-gone");
  return (
    <div className="rounded-row h-row flex w-full max-w-sm items-center justify-between gap-3 border pr-1 pl-3 text-sm">
      <span className="shrink-0">Microphone</span>
      <div className="min-w-0">
        <DevicePicker
          devices={MICROPHONES}
          kind="microphone"
          label="Microphone"
          noneLabel="Off"
          onChange={setValue}
          selectedName="Blue Yeti"
          trigger="inline"
          value={value}
        />
      </div>
    </div>
  );
};

export default DevicePickerInline;
```

## The picker's words

`lib/source-select-state.ts` is pure, so every picker says the same thing in the same state, and the words are tested without a DOM.

| Export | What it does |
| --- | --- |
| `devicePickerTriggerView(input)` | What the closed picker says: label, status and whether it's a placeholder |
| `devicePickerGroups(input)` | The list: the "no device" item, a missing selection, then the matches |
| `devicePickerListStatus(input)` | The one status line, or null |
| `deviceStatusLabel(status)` | "Needs permission", "Unavailable", "Not found", or null |
| `devicePickerCopy(kind)` | Every sentence for a kind |
| `sourceMatchesQuery(device, query)` | The search rule |
| `DEVICE_PICKER_NONE_VALUE` | The "no device" item's value |

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `selectTriggerClassName` | The field trigger is exactly a [Select](/docs/components/select)'s |
| `data-popup-open` | On the trigger while the list is open; an inline trigger takes the hover block |
| `data-placeholder` | A prompt or a state, in the secondary tone |
| `min-h-7` | List rows at the menu item height |
| `--anchor-width` | The field list is as wide as its trigger |

## Keyboard

| Key | Action |
| --- | --- |
| <kbd>Enter</kbd> <kbd>Space</kbd> | On the trigger, opens the list |
| <kbd>↑</kbd> <kbd>↓</kbd> | Moves the highlight, which starts on the current choice |
| <kbd>Enter</kbd> | Chooses the highlighted device |
| <kbd>Esc</kbd> | Closes without changing the choice, and clears the search |

## Accessibility

The trigger is a `combobox` named by `label`, with `aria-haspopup="listbox"`, or `"dialog"` with a search field. A field trigger is labelled by its visible label (`labelHidden` keeps it for screen readers only) and described by `description`, a polite live line for a switch in progress. Without a search field the list takes focus on open and names the highlighted row; with one, the field does. The list's status line is a `status`.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` | `"capture" \| "camera" \| "microphone"` | — | Decides the words. |
| `label` | `string` | — | The accessible name, and a field's visible label. |
| `devices` | `readonly PickerDevice[]` | — | — |
| `value` | `string \| undefined` | — | The chosen device id. |
| `onChange` | `(value: string \| undefined) => void` | — | — |
| `noneLabel` | `string` | — | The "no device" item: "Off", "None". No item when unset. |
| `selectedName` | `string` | — | The saved name, for a chosen device the list doesn't hold. |
| `selectedDevice` | `PickerDevice` | — | The chosen device when it's connected but the list hides it. |
| `selectionLabel` | `string` | — | A choice that isn't a device, such as a test pattern. |
| `discoveryPending` | `boolean` | `false` | Discovery hasn't reported yet. |
| `searchable` | `boolean` | `false` | — |
| `groupByKind` | `boolean` | `false` | Screens and Windows headings. |
| `trigger` | `"field" \| "inline"` | `"field"` | — |
| `description` | `ReactNode` | — | A status line under a field trigger. |
| `statusInTrigger` | `boolean` | `true` | Off where the row's own chip already says it. |
| `disabled` | `boolean` | `false` | — |
| `labelHidden` | `boolean` | `false` | Keeps a field's label for screen readers. |

# Error Boundary (/docs/primitives/error-boundary)

```tsx title="components/examples/error-boundary-demo.tsx"
"use client";

import { useState } from "react";

import { ErrorBoundary, errorDetails } from "@/components/error-boundary";
import type { CaughtError } from "@/components/error-boundary";
import { Button } from "@/components/ui/button";
import {
  Empty,
  EmptyContent,
  EmptyDescription,
  EmptyHeader,
  EmptyTitle,
} from "@/components/ui/empty";

type CopyState = "idle" | "copied" | "failed";

const COPY_LABEL: Record<CopyState, string> = {
  copied: "Copied",
  failed: "Couldn't copy",
  idle: "Copy details",
};

// Quiet on success ("Copied" on the control), loud on failure.
const CopyDetailsButton = ({ details }: { details: string }) => {
  const [state, setState] = useState<CopyState>("idle");
  const copy = async () => {
    try {
      await navigator.clipboard.writeText(details);
      setState("copied");
    } catch {
      setState("failed");
    }
  };
  return (
    <Button onClick={copy} variant="ghost">
      {COPY_LABEL[state]}
    </Button>
  );
};

const PaneErrorPanel = ({
  caught,
  onReset,
}: {
  caught: CaughtError;
  onReset: () => void;
}) => (
  <Empty className="flex-1" role="alert">
    <EmptyHeader>
      <EmptyTitle>This pane hit a problem</EmptyTitle>
      <EmptyDescription>Other panes still work.</EmptyDescription>
    </EmptyHeader>
    <EmptyContent>
      <div className="flex gap-2">
        <Button onClick={onReset}>Reload pane</Button>
        <CopyDetailsButton
          details={errorDetails(caught.error, caught.componentStack)}
        />
      </div>
    </EmptyContent>
  </Empty>
);

const renderPaneError = (caught: CaughtError, reset: () => void) => (
  <PaneErrorPanel caught={caught} onReset={reset} />
);

const ScenePreview = ({ broken }: { broken: boolean }) => {
  if (broken) {
    throw new Error("The Gameplay scene lost its screen source.");
  }
  return (
    <div className="bg-video-ground text-video-ground-muted grid flex-1 place-items-center text-xs">
      Gameplay
    </div>
  );
};

const ErrorBoundaryDemo = () => {
  const [broken, setBroken] = useState(false);
  return (
    <div className="flex w-full max-w-md flex-col items-start gap-3">
      <div className="bg-glass-content rounded-panel flex h-56 w-full overflow-hidden border">
        <ErrorBoundary
          fallback={renderPaneError}
          // The crash happens once, so Reload pane renders the scene again.
          onError={() => setBroken(false)}
        >
          <ScenePreview broken={broken} />
        </ErrorBoundary>
      </div>
      <Button onClick={() => setBroken(true)} variant="secondary">
        Simulate a crash
      </Button>
    </div>
  );
};

export default ErrorBoundaryDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/error-boundary
```

## Usage

```tsx
import { ErrorBoundary, errorDetails } from "@/components/error-boundary";
```

```tsx
<ErrorBoundary
  fallback={(caught, reset) => (
    <PageErrorPanel caught={caught} onReset={reset} />
  )}
  key={page}
>
  <Page />
</ErrorBoundary>
```

Without a boundary, React unmounts the whole root on a render error. In a desktop window that leaves an empty frame with no way back.

Use it twice in a window:

- **Around each page**, keyed by the page. A crash stays in the page, the sidebar and the status bar keep working, and moving to another page starts clean. The panel says "This page hit a problem" and "Other pages still work.", with Reload page and Copy details.
- **Around the window's shell.** The panel keeps a drag band (an empty `h-toolbar` with `[-webkit-app-region:drag]`) so the window still moves, and offers Try again, a reload of the window and Copy details. Wrap that panel in a boundary of its own, with a bare reload button as its fallback, in case the panel itself fails.

Don't use it for errors in event handlers or promises: a boundary catches what throws while rendering, and anything else is yours to report, with a toast.

`errorDetails(error, componentStack)` is what Copy details puts on the clipboard: the stack, then where it rendered. A copy is quiet on success ("Copied" on the button) and loud on failure.

## Accessibility

Give the fallback `role="alert"`, so it's announced as it appears, and lead it with a heading or a title that says what happened. Its first button is the way back.

## API reference

### ErrorBoundary

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | What it guards. |
| `fallback` | `(caught: CaughtError, reset: () => void) => ReactNode` | — | Draws the caught error. reset renders the children again. |
| `onError` | `(error: Error, info: ErrorInfo) => void` | — | Reports the crash: a log line, a crash reporter. React logs it as well. |

### CaughtError

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `error` | `Error` | — | What was thrown. |
| `componentStack` | `string \| null` | — | Where it rendered; null on the first fallback render, then filled in. |

### errorDetails

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `errorDetails(error, componentStack?)` | `string` | — | The stack (or name and message), then "Rendered by:" and the component stack. |

# Primitives (/docs/primitives)

Primitives are what every Videorc screen is built from: grouped lists and their rows, flush panel sections, panes with their toolbars, the status bar, kebab menus and confirm dialogs. Each one is the single answer for its job, so a screen composes them instead of restyling them (see [One primitive per job](/docs/concepts/design-language#one-primitive-per-job)). They're being ported from Videorc now, and each gets its page here as it lands.

# Kebab Context Menu (/docs/primitives/kebab-context-menu)

```tsx title="components/examples/kebab-context-menu-demo.tsx"
"use client";

import {
  DeleteIcon,
  EditIcon,
  FolderIcon,
  SceneIcon,
} from "@/components/icons";
import { KebabContextMenu } from "@/components/kebab-context-menu";
import { KebabMenu } from "@/components/kebab-menu";
import type { KebabMenuItem } from "@/components/kebab-menu";
import { ShortcutKeys } from "@/components/ui/shortcut-keys";

const noop = () => {
  // A demo: the actions do nothing.
};

// One list for both menus, so the ⋯ and the right-click never disagree.
const ITEMS: KebabMenuItem[] = [
  {
    icon: EditIcon,
    id: "rename",
    label: "Rename…",
    onSelect: noop,
    shortcut: <ShortcutKeys accelerator="Enter" />,
  },
  { icon: FolderIcon, id: "reveal", label: "Show in Finder", onSelect: noop },
  {
    destructive: true,
    icon: DeleteIcon,
    id: "delete",
    label: "Delete scene…",
    onSelect: noop,
  },
];

const KebabContextMenuDemo = () => (
  <KebabContextMenu items={ITEMS}>
    <div className="group/kebab-host rounded-row h-row flex w-full max-w-sm items-center gap-2 border pr-1 pl-3 text-sm">
      <SceneIcon aria-hidden className="text-muted-foreground size-4" />
      <span className="flex-1">Screen + camera</span>
      <span className="text-subtle text-meta">Right-click</span>
      <KebabMenu items={ITEMS} label="Actions for Screen + camera" />
    </div>
  </KebabContextMenu>
);

export default KebabContextMenuDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/kebab-context-menu
```

It brings [Kebab Menu](/docs/primitives/kebab-menu) with it, for the item type and the grouping.

## Usage

```tsx
import { KebabContextMenu } from "@/components/kebab-context-menu";
import { KebabMenu } from "@/components/kebab-menu";
```

```tsx
<KebabContextMenu items={items}>
  <div className="group/kebab-host flex items-center">
    Launch demo
    <KebabMenu items={items} label="Actions for Launch demo" />
  </div>
</KebabContextMenu>
```

The child is the row itself: it becomes the trigger and keeps its own element. Pass the same `items` to both menus. Groups, keys, disabled reasons and the destructive item last come out exactly as in the ⋯ menu.

Use it on rows that already have a ⋯ menu, so a right-click finds the same actions. Don't give the context menu items the ⋯ menu doesn't have: a right-click is a shortcut, never the only way.

## Theming

It's [Context Menu](/docs/components/context-menu) underneath: the same float glass, 28 px items and hairline groups as the ⋯ menu.

| Token or attribute | Meaning |
| --- | --- |
| `data-slot="context-menu-trigger"` | Added to the row |
| `select-none` | Added to the row, so a right-click doesn't select its text |

## Keyboard

| Key                       | Action                    |
| ------------------------- | ------------------------- |
| <kbd>↑</kbd> <kbd>↓</kbd> | Moves through the items   |
| <kbd>Enter</kbd>          | Runs the highlighted item |
| <kbd>Esc</kbd>            | Closes the menu           |

## Accessibility

A context menu has no keyboard way in of its own, which is why it only ever repeats the row's ⋯ menu: keyboard and screen reader users reach every action there.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `KebabMenuItem[]` | — | The same list the row's ⋯ menu takes. |
| `children` | `ReactElement` | — | The row: it becomes the trigger. |
| `onOpenChange` | `(open: boolean) => void` | — | — |

# Kebab Menu (/docs/primitives/kebab-menu)

```tsx title="components/examples/kebab-menu-demo.tsx"
"use client";

import { useState } from "react";

import { ConfirmDialog } from "@/components/confirm-dialog";
import {
  DeleteIcon,
  EditIcon,
  FolderIcon,
  VideoFileIcon,
} from "@/components/icons";
import { KebabMenu } from "@/components/kebab-menu";

const RECORDINGS = [
  { id: "launch", length: "41:10", name: "Launch demo" },
  { id: "qa", length: "1:02:45", name: "Friday Q&A" },
  { id: "walkthrough", length: "12:31", name: "Studio walkthrough" },
];

const noop = () => {
  // A demo: Rename and Show in Finder do nothing.
};

const KebabMenuDemo = () => {
  const [recordings, setRecordings] = useState(RECORDINGS);
  const [pending, setPending] = useState<string | null>(null);
  const target = recordings.find((recording) => recording.id === pending);

  return (
    <div className="w-full max-w-sm">
      <ul className="divide-border rounded-row flex flex-col divide-y border">
        {recordings.map((recording) => (
          <li
            className="group/kebab-host h-row flex items-center gap-2 pr-1 pl-3"
            key={recording.id}
          >
            <VideoFileIcon
              aria-hidden
              className="text-muted-foreground size-4 shrink-0"
            />
            <span className="min-w-0 flex-1 truncate text-sm">
              {recording.name}
            </span>
            <span className="text-muted-foreground text-meta tabular-nums">
              {recording.length}
            </span>
            <KebabMenu
              items={[
                {
                  icon: EditIcon,
                  id: "rename",
                  label: "Rename…",
                  onSelect: noop,
                },
                {
                  icon: FolderIcon,
                  id: "reveal",
                  label: "Show in Finder",
                  onSelect: noop,
                },
                {
                  destructive: true,
                  icon: DeleteIcon,
                  id: "delete",
                  label: "Delete…",
                  onSelect: () => setPending(recording.id),
                },
              ]}
              label={`Actions for ${recording.name}`}
              reveal="hover"
            />
          </li>
        ))}
      </ul>
      <ConfirmDialog
        confirmLabel="Delete recording"
        description={`“${target?.name ?? ""}” and its markers move to the Trash.`}
        onCancel={() => setPending(null)}
        onConfirm={() => {
          setRecordings((current) =>
            current.filter((recording) => recording.id !== pending)
          );
          setPending(null);
        }}
        open={target !== undefined}
        title="Delete recording?"
      />
    </div>
  );
};

export default KebabMenuDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/kebab-menu
```

## Usage

```tsx
import { KebabMenu } from "@/components/kebab-menu";
```

```tsx
<KebabMenu
  items={[
    { id: "rename", label: "Rename…", icon: EditIcon, onSelect: rename },
    {
      id: "delete",
      label: "Delete…",
      destructive: true,
      onSelect: askToDelete,
    },
  ]}
  label="Actions for Launch demo"
/>
```

Use it for per-item actions in every list and card: recordings, assets, scenes, scheduled livestreams, chat rows. The row's primary action stays a click on the row; the menu holds what you do less often.

Don't build a menu by hand for a row, and don't put the row's one main action in it.

## Examples

### Groups, keys and a busy item

Items with the same `group` sit together, a hairline between groups, in the order each group first appears. Destructive items always go last, in a group of their own. `shortcut` takes a [Shortcut Keys](/docs/components/shortcut-keys). While an item's work runs, `busy` swaps the dots for a spinner, and a disabled item says why on hover.

```tsx title="components/examples/kebab-menu-groups.tsx"
"use client";

import { useState } from "react";

import {
  CopyIcon,
  DeleteIcon,
  EditIcon,
  MarkerIcon,
  PlayIcon,
  RepairIcon,
} from "@/components/icons";
import { KebabMenu } from "@/components/kebab-menu";
import type { KebabMenuItem } from "@/components/kebab-menu";
import { ShortcutKeys } from "@/components/ui/shortcut-keys";

const CHECK_TAKES_MS = 1500;

const noop = () => {
  // A demo: most actions do nothing.
};

const KebabMenuGroups = () => {
  const [checking, setChecking] = useState(false);
  const check = () => {
    setChecking(true);
    setTimeout(() => setChecking(false), CHECK_TAKES_MS);
  };
  const items: KebabMenuItem[] = [
    {
      group: "open",
      icon: PlayIcon,
      id: "play",
      label: "Play",
      onSelect: noop,
      shortcut: <ShortcutKeys accelerator="Space" />,
    },
    {
      group: "open",
      icon: MarkerIcon,
      id: "markers",
      label: "Show markers",
      onSelect: noop,
    },
    {
      group: "edit",
      icon: EditIcon,
      id: "rename",
      label: "Rename…",
      onSelect: noop,
      shortcut: <ShortcutKeys accelerator="Enter" />,
    },
    {
      group: "edit",
      icon: CopyIcon,
      id: "duplicate",
      label: "Duplicate",
      onSelect: noop,
    },
    {
      disabled: checking,
      disabledReason: "Wait for the check to finish.",
      group: "repair",
      icon: RepairIcon,
      id: "check",
      label: checking ? "Checking…" : "Check recording",
      onSelect: check,
    },
    {
      destructive: true,
      disabled: checking,
      disabledReason: "Wait for the check to finish.",
      icon: DeleteIcon,
      id: "delete",
      label: "Delete…",
      onSelect: noop,
    },
  ];

  return (
    <div className="flex items-center gap-3 text-sm">
      <span>Launch demo</span>
      <KebabMenu
        busy={checking}
        items={items}
        label="Actions for Launch demo"
      />
    </div>
  );
};

export default KebabMenuGroups;
```

### Revealed on hover

`reveal="hover"` hides the trigger until its host row is hovered or holds focus. Mark the row with `group/kebab-host`. The trigger stays visible while its menu is open, while it has keyboard focus and while it's busy.

```tsx title="components/examples/media-card-backgrounds.tsx"
"use client";

import { DeleteIcon, EditIcon, ImageIcon } from "@/components/icons";
import { KebabMenu } from "@/components/kebab-menu";
import { MediaCard } from "@/components/media-card";

const BACKGROUNDS = ["Studio wall", "Night city", "Soft gradient"];

const noop = () => {
  // A demo: the actions do nothing.
};

const MediaCardBackgrounds = () => (
  <div className="grid w-full max-w-lg grid-cols-3 gap-3">
    {BACKGROUNDS.map((name) => (
      <MediaCard className="group/kebab-host gap-2 p-2" key={name}>
        <div className="bg-muted text-muted-foreground rounded-chip flex aspect-video items-center justify-center">
          <ImageIcon aria-hidden className="size-6" weight="duotone" />
        </div>
        <div className="flex items-center gap-1">
          <span className="min-w-0 flex-1 truncate text-sm">{name}</span>
          <KebabMenu
            items={[
              {
                icon: EditIcon,
                id: "rename",
                label: "Rename…",
                onSelect: noop,
              },
              {
                destructive: true,
                icon: DeleteIcon,
                id: "delete",
                label: "Delete",
                onSelect: noop,
              },
            ]}
            label={`Actions for ${name}`}
            reveal="hover"
          />
        </div>
      </MediaCard>
    ))}
  </div>
);

export default MediaCardBackgrounds;
```

### With a confirm dialog

A destructive item that can't be undone opens a [Confirm Dialog](/docs/primitives/confirm-dialog), and its label ends in "…". The recordings list above does this for Delete.

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `Button` `ghost`, `size="icon"` | The 28 px trigger |
| `group/kebab-host` | The row the trigger waits for with `reveal="hover"` |
| `data-popup-open` | On the trigger while its menu is open; keeps it visible |
| `aria-busy` | On the trigger while `busy`; keeps it visible |

## Keyboard

| Key | Action |
| --- | --- |
| <kbd>Enter</kbd> <kbd>Space</kbd> | On the trigger, opens the menu |
| <kbd>↑</kbd> <kbd>↓</kbd> | Moves through the items, disabled ones included |
| <kbd>Enter</kbd> | Runs the highlighted item |
| <kbd>Esc</kbd> | Closes the menu and returns focus to the trigger |

## Accessibility

The trigger is a button named by `label`: name the item it acts on ("Actions for Launch demo"), never just "More". A click on the trigger or in the menu never reaches a clickable row behind it. A disabled item stays in the arrow-key order and is described by its `disabledReason`, through [Disabled Reason](/docs/components/disabled-reason).

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `KebabMenuItem[]` | — | — |
| `label` | `string` | `"More actions"` | The trigger's accessible name. |
| `busy` | `boolean` | `false` | An item's work is running: a spinner replaces the dots. |
| `disabled` | `boolean` | `false` | The whole menu is unavailable. |
| `reveal` | `"always" \| "hover"` | `"always"` | hover: hidden until the group/kebab-host row is hovered or focused. |
| `tabIndex` | `number` | — | -1 in a roving-focus row that isn't the active one. |
| `className` | `string` | — | Layout for the trigger. |

### KebabMenuItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | — | — |
| `label` | `string` | — | — |
| `icon` | `AppIcon` | — | — |
| `destructive` | `boolean` | `false` | The destructive tone, last, in a group of its own. |
| `disabled` | `boolean` | `false` | — |
| `disabledReason` | `string \| null` | — | Why a disabled item is off, in one sentence. |
| `group` | `string` | — | Items with the same group sit together. |
| `shortcut` | `ReactNode` | — | The item's keys, right-aligned. |
| `onSelect` | `() => void` | — | Runs when the item is chosen, by click or by key. |

`kebabMenuGroups(items)` returns the items in their groups, destructive last, for a menu of your own that should agree with this one.

# List Row (/docs/primitives/list-row)

```tsx title="components/examples/list-row-demo.tsx"
"use client";

import { CameraIcon, MicrophoneIcon, WarningIcon } from "@/components/icons";
import { GroupedList, ListRow } from "@/components/list-row";

const ListRowDemo = () => (
  <div className="flex w-full max-w-md flex-col gap-4">
    <GroupedList aria-label="Cameras" label="Cameras">
      <ListRow
        context="Built-in"
        icon={<CameraIcon />}
        meta="In use"
        title="FaceTime HD Camera"
      />
      <ListRow
        context="USB"
        icon={<CameraIcon />}
        meta="Connected"
        title="Sony ZV-E10"
      />
    </GroupedList>
    <GroupedList aria-label="Microphones" label="Microphones">
      <ListRow
        context="USB"
        icon={<MicrophoneIcon />}
        meta="In use"
        title="Shure MV7"
      />
      <ListRow
        context="Bluetooth"
        icon={<MicrophoneIcon />}
        meta="Not responding"
        statusIcons={<WarningIcon aria-hidden />}
        title="AirPods Pro"
      />
    </GroupedList>
  </div>
);

export default ListRowDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/list-row
```

## Usage

```tsx
import { GroupedList, ListRow, ListRowButton } from "@/components/list-row";
```

```tsx
<GroupedList label="Cameras">
  <ListRow
    context="Built-in"
    icon={<CameraIcon />}
    meta="In use"
    title="FaceTime HD Camera"
  />
</GroupedList>
```

Use it for sets of like things: sources, devices, destinations, scenes, settings. Lists, not card stacks: a card is only for an object with a picture, such as a scene thumbnail or a background.

Don't hand-roll an icon, title and meta row, and don't put cards inside a grouped list. A fact row that jumps to the page owning its value is a [Navigable Row](/docs/primitives/navigable-row).

## Anatomy

```tsx
<GroupedList label>
  <ListRow leading icon title context alias statusIcons meta>
    {/* trailing controls */}
  </ListRow>
</GroupedList>
```

## Examples

### A row with its own controls

A row that holds a control, such as a switch, stays a `div`. Put a `ListRowButton` in its `title` and give the row `relative`: the button stretches over the whole row, so a click anywhere on it acts, while the switch stays its sibling instead of nesting inside a button. `interactive` adds the hover.

```tsx title="components/examples/list-row-controls.tsx"
"use client";

import { useState } from "react";

import { TwitchIcon, YoutubeIcon } from "@/components/icons";
import { GroupedList, ListRow, ListRowButton } from "@/components/list-row";
import { Switch } from "@/components/ui/switch";

const DESTINATIONS = [
  {
    account: "Maya Streams",
    icon: <YoutubeIcon className="text-platform-youtube" weight="fill" />,
    id: "youtube",
    name: "YouTube",
  },
  {
    account: "maya_streams",
    icon: <TwitchIcon className="text-platform-twitch-ink" weight="fill" />,
    id: "twitch",
    name: "Twitch",
  },
] as const;

const ListRowControls = () => {
  const [selected, setSelected] = useState<string>("youtube");
  const [on, setOn] = useState<Record<string, boolean>>({
    twitch: false,
    youtube: true,
  });
  return (
    <GroupedList
      aria-label="Destinations"
      className="w-full max-w-md"
      label="Destinations"
    >
      {DESTINATIONS.map((destination) => (
        <ListRow
          className="relative"
          context={destination.account}
          icon={destination.icon}
          interactive
          key={destination.id}
          selected={selected === destination.id}
          title={
            <ListRowButton onClick={() => setSelected(destination.id)}>
              {destination.name}
            </ListRowButton>
          }
        >
          <Switch
            aria-label={`Stream to ${destination.name}`}
            checked={on[destination.id]}
            onCheckedChange={(checked) =>
              setOn((current) => ({ ...current, [destination.id]: checked }))
            }
          />
        </ListRow>
      ))}
    </GroupedList>
  );
};

export default ListRowControls;
```

### The whole row as a button

`as="button"` makes the row one button, with the hover and the focus ring. `selected` draws the accent block; pair it with `aria-pressed` or `aria-current`. `compact` is 28 px.

```tsx title="components/examples/list-row-button.tsx"
"use client";

import { useState } from "react";

import { SceneIcon } from "@/components/icons";
import { GroupedList, ListRow } from "@/components/list-row";

const SCENES = [
  { name: "Just chatting", sources: "2 sources" },
  { name: "Gameplay", sources: "4 sources" },
  { name: "Be right back", sources: "1 source" },
] as const;

const ListRowButtonExample = () => {
  const [scene, setScene] = useState<string>("Gameplay");
  return (
    <GroupedList aria-label="Scenes" className="w-full max-w-xs" label="Scenes">
      {SCENES.map(({ name, sources }) => (
        <ListRow
          aria-pressed={scene === name}
          as="button"
          compact
          icon={<SceneIcon />}
          key={name}
          meta={sources}
          onClick={() => setScene(name)}
          selected={scene === name}
          title={name}
        />
      ))}
    </GroupedList>
  );
};

export default ListRowButtonExample;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `h-row`, `h-row-compact` | 32 px, or 28 px when `compact` |
| `rounded-row` | 8 px on a row alone; none inside a GroupedList, which owns the radius |
| `bg-inset`, `divide-border` | The grouped list's inset fill and its hairlines |
| `bg-accent` | The hover of an interactive row, and the selected row |
| `text-meta` | The 12 px meta label |
| `data-selected` | On a selected row |
| `data-slot="platform-mark"` | On a platform mark in the icon tile: it's never clipped to the chip radius |
| `data-slot` | `list-row`, `list-row-icon`, `list-row-title`, `list-row-context`, `list-row-meta`, `grouped-list`, `list-row-button` |

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Moves to a row that's a button or holds a ListRowButton, then to the row's own controls |
| `Enter`, `Space` | Activates it |

## Accessibility

A fact row is plain text. A row that's a button is named by its content, the title, context and meta in order, so keep the meta short. Selection is a block of colour: say it with `aria-pressed` or `aria-current` too. A trailing control needs its own name ("Stream to YouTube").

GroupedList passes its attributes to the list itself, so `aria-label` names the group for assistive tech.

## API reference

### ListRow

Every `div` attribute, or every `button` attribute with `as="button"`, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `"div" \| "button"` | `"div"` | — |
| `title` | `ReactNode` | — | The row's title. It's never the native tooltip attribute. |
| `icon` | `ReactNode` | — | The 20 px icon tile: the source's or the app's own icon. |
| `leading` | `ReactNode` | — | A control before the title, never clipped like the icon tile. |
| `context` | `ReactNode` | — | Secondary context after the title: platform, owner, kind. |
| `alias` | `ReactNode` | — | Key chips after the context. |
| `statusIcons` | `ReactNode` | — | Small status icons before the meta. |
| `meta` | `ReactNode` | — | Right-aligned secondary metadata. |
| `selected` | `boolean` | `false` | The accent block and data-selected. |
| `interactive` | `boolean` | `true with as="button"` | The hover. Off by default: most rows are facts. |
| `compact` | `boolean` | `false` | 28 px instead of 32 px. |
| `children` | `ReactNode` | — | Trailing controls, before the status icons and the meta. |

### GroupedList

Every `div` attribute, on the list itself, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `ReactNode` | — | A Section Label over the group. |

### ListRowButton

Every `button` attribute. Give its ListRow `relative`, and position any control in the row that must stay clickable (Switch already is).

# Lock Alert (/docs/primitives/lock-alert)

```tsx title="components/examples/lock-alert-demo.tsx"
"use client";

import { LockAlert } from "@/components/lock-alert";
import { SettingsRow } from "@/components/ui/field";
import { Switch } from "@/components/ui/switch";

const PREMIUM_URL = "https://www.videorc.com/premium";

const signIn = () => {
  // A demo: your app starts its sign-in here.
};

const LockAlertDemo = () => (
  <div className="flex w-full max-w-md flex-col gap-3">
    <LockAlert
      action={{ kind: "view-premium", url: PREMIUM_URL }}
      reason="Live captions are part of Videorc Premium."
    />
    {/* The feature stays on screen behind the lock, disabled. */}
    <SettingsRow className="mx-3 w-auto" label="Show captions on stream">
      <Switch disabled />
    </SettingsRow>
    <LockAlert
      action={{ kind: "sign-in", onClick: signIn }}
      reason="Sign in to use Buddy."
    />
  </div>
);

export default LockAlertDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/lock-alert
```

## Usage

```tsx
import {
  LockAlert,
  OfflineAlert,
  SessionLockAlert,
} from "@/components/lock-alert";
```

```tsx
<LockAlert
  action={{ kind: "view-premium", url: premiumUrl, onClick: openExternal }}
  reason="Live captions are part of Videorc Premium."
/>
```

Locked means disabled with one reason. The alert leads the tab or section it locks, and every control under it is disabled. A Premium feature stays on screen behind the lock, never hidden: the locked page is what sells it.

Use it for a section a plan, an account, a running session or a reconnect turns off. Don't hide the locked controls, and don't offer more than one action. For a single disabled control, use [Disabled Reason](/docs/components/disabled-reason) instead.

## The action

Your app decides whether a lock has an action (is this a Premium gate? is anyone signed in?) and passes the resolved one. A limit or a turned-off feature locks with its reason alone.

- `{ kind: "sign-in", onClick }` reads "Sign in" and calls `onClick`: start your app's sign-in there.
- `{ kind: "view-premium", url, onClick? }` reads "View Premium". With `onClick` it's a button that calls `onClick(url)`, so an Electron app can hand the link to the system browser. Without one it's a link that opens `url` in a new tab.

Either can bring its own words in `label`. The Premium sentence is always the same: `{Feature} is part of Videorc Premium.`

## Examples

### Recording, live and reconnecting

`SessionLockAlert` says the one wording for controls a running recording or livestream locks. Give it `locks` to name them, as a plural subject, when a page holds more than one kind of control. `OfflineAlert` is for controls that wait for the app to reconnect. Either takes a `reason` to replace its words.

```tsx title="components/examples/lock-alert-session.tsx"
"use client";

import { OfflineAlert, SessionLockAlert } from "@/components/lock-alert";

const LockAlertSession = () => (
  <div className="flex w-full max-w-md flex-col gap-3">
    <SessionLockAlert />
    <SessionLockAlert locks="Destinations and stream details" />
    <OfflineAlert />
  </div>
);

export default LockAlertSession;
```

## Theming

It's an [Alert](/docs/components/alert) with `variant="locked"`.

| Token or attribute | Meaning |
| --- | --- |
| `data-variant="locked"` | The neutral tint, the lock icon and the reason in secondary text |
| `Button` `outline`, `size="xs"` | The action |

## Accessibility

It's a polite `status`, so a lock that appears (when a recording starts) is announced without interrupting. The action is a real button, or a real link when it only opens a page.

## API reference

### LockAlert

Every [Alert](/docs/components/alert) prop except `variant`, `icon` and `children`, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `reason` | `ReactNode` | — | One line: why the controls under it are off. |
| `action` | `LockAlertAction \| null` | `null` | The one thing that unlocks it. |

### SessionLockAlert

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `locks` | `string` | — | What it locks, as a plural subject: "Destinations and stream details". |
| `reason` | `ReactNode` | — | Replaces the wording. |

### OfflineAlert

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `reason` | `ReactNode` | `OFFLINE_LOCK_REASON` | Replaces the wording. |

`unlockActionLabel(action)` is exported too. The wording itself, `SESSION_LOCK_REASON`, `OFFLINE_LOCK_REASON` and `sessionLockReason(locks?)`, lives in `@/lib/lock-reason`, which comes with Lock Alert, so a toast, a tooltip or code that isn't UI can say the same words without importing a component.

# Media Card (/docs/primitives/media-card)

```tsx title="components/examples/media-card-demo.tsx"
"use client";

import { useState } from "react";

import { CameraIcon, DisplayIcon, SceneIcon } from "@/components/icons";
import type { AppIcon } from "@/components/icons";
import { MediaCard } from "@/components/media-card";

const SCENES: { id: string; name: string; icon: AppIcon }[] = [
  { icon: SceneIcon, id: "screen-camera", name: "Screen + camera" },
  { icon: DisplayIcon, id: "screen", name: "Screen only" },
  { icon: CameraIcon, id: "camera", name: "Camera only" },
];

const MediaCardDemo = () => {
  const [current, setCurrent] = useState("screen-camera");
  return (
    <div className="grid w-full max-w-lg grid-cols-3 gap-3">
      {SCENES.map((scene) => (
        <MediaCard
          aria-pressed={scene.id === current}
          className="gap-2 p-2 text-left"
          interactive
          key={scene.id}
          onClick={() => setCurrent(scene.id)}
          // oxlint-disable-next-line jsx-a11y/control-has-associated-label -- Base UI renders the label into it.
          render={<button type="button" />}
          selected={scene.id === current}
        >
          <span className="bg-muted text-muted-foreground rounded-chip flex aspect-video items-center justify-center">
            <scene.icon aria-hidden className="size-6" weight="duotone" />
          </span>
          <span className="truncate text-sm font-medium">{scene.name}</span>
        </MediaCard>
      ))}
    </div>
  );
};

export default MediaCardDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/media-card
```

## Usage

```tsx
import { MediaCard } from "@/components/media-card";
```

```tsx
<MediaCard
  interactive
  onClick={() => setScene(scene.id)}
  render={<button type="button" />}
  selected={scene.id === current}
>
  <SceneThumbnail scene={scene} />
  {scene.name}
</MediaCard>
```

Use it for objects with a picture: a scene thumbnail, a background, a takeover screen. Lists of like things without one stay rows; only a picture earns a card.

Don't put a card on a card, give it a shadow, or mark the selected one with a color.

## Examples

### With a menu

A card that isn't itself a button can hold a [Kebab Menu](/docs/primitives/kebab-menu). Mark the card `group/kebab-host` and the ⋯ waits for its hover.

```tsx title="components/examples/media-card-backgrounds.tsx"
"use client";

import { DeleteIcon, EditIcon, ImageIcon } from "@/components/icons";
import { KebabMenu } from "@/components/kebab-menu";
import { MediaCard } from "@/components/media-card";

const BACKGROUNDS = ["Studio wall", "Night city", "Soft gradient"];

const noop = () => {
  // A demo: the actions do nothing.
};

const MediaCardBackgrounds = () => (
  <div className="grid w-full max-w-lg grid-cols-3 gap-3">
    {BACKGROUNDS.map((name) => (
      <MediaCard className="group/kebab-host gap-2 p-2" key={name}>
        <div className="bg-muted text-muted-foreground rounded-chip flex aspect-video items-center justify-center">
          <ImageIcon aria-hidden className="size-6" weight="duotone" />
        </div>
        <div className="flex items-center gap-1">
          <span className="min-w-0 flex-1 truncate text-sm">{name}</span>
          <KebabMenu
            items={[
              {
                icon: EditIcon,
                id: "rename",
                label: "Rename…",
                onSelect: noop,
              },
              {
                destructive: true,
                icon: DeleteIcon,
                id: "delete",
                label: "Delete",
                onSelect: noop,
              },
            ]}
            label={`Actions for ${name}`}
            reveal="hover"
          />
        </div>
      </MediaCard>
    ))}
  </div>
);

export default MediaCardBackgrounds;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `rounded-row` | The 8 px card radius |
| `bg-foreground/4`, `border-border` | The 4% fill and the hairline |
| `hover:bg-accent` | The hover block, with `interactive` |
| `chrome-plate`, `border-foreground/25` | The one in use: a brighter rim on the plate |
| `data-selected` | Set while `selected` |
| `data-slot="media-card"` | On whichever element carries the look |

## Accessibility

A card you click is a `<button>` (or a link): pass it to `render`. When the card is one of a set and `selected` marks the one in use, say so with `aria-pressed` or by the set's own semantics, since the plate alone is visual.

## API reference

Every [Base UI useRender](https://base-ui.com/react/utils/use-render) prop, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `selected` | `boolean` | `false` | The one in use: a brighter rim on the chrome plate. |
| `interactive` | `boolean` | `false` | The hover block, for a card that is a button or a link. |
| `render` | `ReactElement \| (props, state) => ReactElement` | — | Puts the look on another element, such as a button. |

# Navigable Row (/docs/primitives/navigable-row)

```tsx title="components/examples/navigable-row-demo.tsx"
"use client";

import { useState } from "react";

import {
  CameraIcon,
  GaugeIcon,
  LivestreamIcon,
  MicrophoneIcon,
  OutputIcon,
} from "@/components/icons";
import { GroupedList } from "@/components/list-row";
import {
  NavigableRow,
  NavigableRowHintLines,
} from "@/components/navigable-row";

const NavigableRowDemo = () => {
  const [opened, setOpened] = useState<string | null>(null);
  return (
    <div className="flex w-full max-w-sm flex-col gap-2">
      <GroupedList aria-label="Session" label="Session">
        <NavigableRow
          icon={CameraIcon}
          label="Camera"
          onNavigate={() => setOpened("Sources")}
          value="FaceTime HD Camera"
        />
        <NavigableRow
          icon={MicrophoneIcon}
          label="Microphone"
          onNavigate={() => setOpened("Sources")}
          value="Shure MV7"
        />
        <NavigableRow
          hint={
            <NavigableRowHintLines
              lines={["1920 × 1080", "60 fps", "12 Mbps"]}
            />
          }
          icon={OutputIcon}
          label="Recording"
          onNavigate={() => setOpened("Output")}
          value="1080p · 60 fps"
        />
        <NavigableRow
          hint={<NavigableRowHintLines lines={["YouTube", "Twitch"]} />}
          icon={LivestreamIcon}
          label="Destinations"
          onNavigate={() => setOpened("Livestream")}
          value="2 on"
        />
        <NavigableRow icon={GaugeIcon} label="Dropped frames" value="0" />
      </GroupedList>
      <p aria-live="polite" className="text-meta text-muted-foreground px-1">
        {opened ? `Opened ${opened}.` : "Choose a row to open its page."}
      </p>
    </div>
  );
};

export default NavigableRowDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/navigable-row
```

## Usage

```tsx
import {
  NavigableRow,
  NavigableRowHintLines,
} from "@/components/navigable-row";
```

```tsx
<GroupedList label="Session">
  <NavigableRow
    icon={CameraIcon}
    label="Camera"
    onNavigate={() => openPage("sources")}
    value="FaceTime HD Camera"
  />
</GroupedList>
```

Use it for a fact another page owns: the Studio's Session rows, a Settings row that points at Output or Livestream. Pass `onNavigate` only when the value lives somewhere else, and send it to the one page that owns it.

Don't use it for a row that changes something in place: that's a [List Row](/docs/primitives/list-row) with a control, or a [Settings row](/docs/components/field).

A long text value gives way first: the label keeps its width and the value truncates ("Microphone" beside "Microphone (HD Pro Webcam C920)", never "Mic…"). A control value, such as a Stop button, keeps its width instead, and the label truncates.

When a value sums up several facts ("1080p · 60 fps", "2 on"), `hint` shows them on hover and on focus. `NavigableRowHintLines` puts one fact on each line. Only a row that navigates takes a hint, since only a button takes focus.

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `h-row`, `px-3` | The 32 px row with 12 px padding |
| `rounded-row` | 8 px on a row alone; none inside a GroupedList |
| `text-muted-foreground` | The icon, the label and the chevron |
| `text-foreground` | The value, at weight 500 |
| `hover:bg-accent` | The hover of a row that navigates |
| `data-slot` | `navigable-row` on the row, `navigable-row-label` and `navigable-row-value` on its parts, `navigable-row-hint` on a hint's lines |

## Keyboard

| Key              | Action                                           |
| ---------------- | ------------------------------------------------ |
| `Tab`            | Moves to a row that navigates and shows its hint |
| `Enter`, `Space` | Opens the value's page                           |

## Accessibility

A row that navigates is a button named by its label and value; the chevron is decorative. Its hint is a [Tooltip](/docs/components/tooltip), never a native `title`. A fact row is plain text.

## API reference

### NavigableRow

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | — | What the value is. |
| `value` | `ReactNode` | — | The fact. A string truncates. |
| `icon` | `AppIcon` | — | A 16 px duotone icon before the label. |
| `onNavigate` | `() => void` | — | Makes the row a button with a chevron that opens the value's page. |
| `hint` | `ReactNode` | — | The facts the value stands for, on hover and on focus. Only with onNavigate. |
| `className` | `string` | — | — |

### NavigableRowHintLines

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `lines` | `readonly string[]` | — | One fact per line. |

# Page Tabs (/docs/primitives/page-tabs)

```tsx title="components/examples/page-tabs-demo.tsx"
"use client";

import { useState } from "react";

import { PageStack } from "@/components/page";
import { PageTabs } from "@/components/page-tabs";
import { Pane, PaneBody, Toolbar } from "@/components/pane";
import { PanelSection } from "@/components/panel-section";
import { FieldGroup, SettingsRow } from "@/components/ui/field";
import { ShortcutKeys } from "@/components/ui/shortcut-keys";
import { Switch } from "@/components/ui/switch";
import { TabsContent } from "@/components/ui/tabs";

type Tab = "general" | "recording" | "shortcuts";

const TABS = [
  { id: "general", label: "General" },
  { id: "recording", label: "Recording" },
  { id: "shortcuts", label: "Shortcuts" },
] as const;

const SHORTCUTS = [
  { accelerator: "CmdOrCtrl+K", name: "Search" },
  { accelerator: "CmdOrCtrl+P", name: "Open Preview" },
  { accelerator: "CmdOrCtrl+Shift+N", name: "Open Notes" },
  { accelerator: "CmdOrCtrl+Shift+J", name: "Open Stream Manager" },
] as const;

const PageTabsDemo = () => {
  const [tab, setTab] = useState<Tab>("general");
  const [launch, setLaunch] = useState(false);
  const [updates, setUpdates] = useState(true);
  const [saveLocal, setSaveLocal] = useState(true);
  return (
    <div className="bg-glass-content rounded-panel flex h-80 w-full max-w-xl overflow-hidden border">
      <Pane>
        <Toolbar title="Settings" />
        <PaneBody>
          <PageTabs<Tab>
            label="Settings sections"
            onValueChange={setTab}
            tabs={TABS}
            value={tab}
          >
            <TabsContent value="general">
              <PageStack>
                <PanelSection
                  description="How Videorc starts and stays current."
                  title="App"
                >
                  <FieldGroup variant="grouped">
                    <SettingsRow label="Open at login">
                      <Switch checked={launch} onCheckedChange={setLaunch} />
                    </SettingsRow>
                    <SettingsRow
                      description="Updates install the next time you quit."
                      label="Download updates"
                    >
                      <Switch checked={updates} onCheckedChange={setUpdates} />
                    </SettingsRow>
                  </FieldGroup>
                </PanelSection>
              </PageStack>
            </TabsContent>
            <TabsContent value="recording">
              <PageStack>
                <PanelSection
                  description="Recordings save to ~/Movies/Videorc."
                  title="Recording"
                >
                  <FieldGroup variant="grouped">
                    <SettingsRow
                      description="Keep a copy on this computer while you stream."
                      label="Save local recording"
                    >
                      <Switch
                        checked={saveLocal}
                        onCheckedChange={setSaveLocal}
                      />
                    </SettingsRow>
                  </FieldGroup>
                </PanelSection>
              </PageStack>
            </TabsContent>
            <TabsContent value="shortcuts">
              <PageStack>
                <PanelSection
                  description="They work while any Videorc window is in front."
                  title="Windows"
                >
                  <dl className="flex flex-col gap-2 text-sm">
                    {SHORTCUTS.map(({ accelerator, name }) => (
                      <div
                        className="flex items-center justify-between"
                        key={name}
                      >
                        <dt className="text-muted-foreground">{name}</dt>
                        <dd>
                          <ShortcutKeys accelerator={accelerator} />
                        </dd>
                      </div>
                    ))}
                  </dl>
                </PanelSection>
              </PageStack>
            </TabsContent>
          </PageTabs>
        </PaneBody>
      </Pane>
    </div>
  );
};

export default PageTabsDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/page-tabs
```

## Usage

```tsx
import { PageTabs } from "@/components/page-tabs";
import { TabsContent } from "@/components/ui/tabs";
```

```tsx
<PageTabs
  label="Settings sections"
  onValueChange={setTab}
  tabs={[
    { id: "general", label: "General" },
    { id: "recording", label: "Recording" },
  ]}
  value={tab}
>
  <TabsContent value="general">…</TabsContent>
  <TabsContent value="recording">…</TabsContent>
</PageTabs>
```

Use it for a page whose parts each answer one question: Settings, Livestream, Buddy. A tab's body is a [ConfigGrid](/docs/primitives/page) of two sections with `CONFIG_GRID_PAIR`, or a `PageStack` for one.

PageTabs keeps no state. Keep the tab in the app: remember the last one used on this device, open a named tab from a link, and list every tab in the command palette.

Don't put tabs in the toolbar, which holds only the title. Don't use tabs to choose a value either: that's a [Segmented Control](/docs/components/segmented-control).

## Anatomy

PageTabs draws the strip and the tab list from `tabs`; you pass the panels.

```tsx
<PageTabs>
  <PaneStrip>
    <TabsList>
      <TabsTrigger />
    </TabsList>
  </PaneStrip>
  <div data-slot="page-tabs-scroll">
    <TabsContent />
  </div>
</PageTabs>
```

The root is a [Tabs](/docs/components/tabs) carrying `PANE_OWNS_SCROLL`, so the [PaneBody](/docs/primitives/pane) around it stops scrolling, and the region under the strip is keyed by the tab.

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `PaneStrip` | The pinned strip: a hairline below, the gutter at the sides |
| `TabsList` | The glass segmented track; the selected tab is a chrome plate |
| `data-pane-scroll="own"` | On the root, from `PANE_OWNS_SCROLL` |
| `data-slot="page-tabs-scroll"` | The one region that scrolls |
| `triggerAttribute` | A `data-` attribute on each trigger, holding its tab's id |

## Keyboard

| Key                       | Action                                       |
| ------------------------- | -------------------------------------------- |
| `ArrowRight`, `ArrowLeft` | Moves between tabs and shows each one        |
| `Home`, `End`             | Moves to the first or last tab               |
| `Tab`                     | Moves from the tab list into the tab's panel |

## Accessibility

`label` names the tab list ("Settings sections"); Base UI wires the tabs to their panels. The scroll region is keyed by the tab, so every change, by a click, the arrow keys or a link, starts the new tab at the top while focus stays on the tab list.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tabs` | `readonly { id: Id; label: ReactNode }[]` | — | The tabs, in order. |
| `value` | `Id` | — | The tab on screen. |
| `onValueChange` | `(tab: Id) => void` | — | Called with the typed id of the tab the streamer picks. |
| `label` | `string` | — | The tab list's accessible name. |
| `triggerAttribute` | ``data-${string}`` | — | A data attribute each trigger carries with its tab's id, so tests and links can find a tab. |
| `testId` | `string` | — | data-testid on the root. |
| `children` | `ReactNode` | — | The TabsContent panels. |

# Page (/docs/primitives/page)

```tsx title="components/examples/page-demo.tsx"
"use client";

import { useState } from "react";

import { CONFIG_GRID_PAIR, ConfigGrid, PageHeader } from "@/components/page";
import { Pane, PaneBody, Toolbar } from "@/components/pane";
import { PanelSection } from "@/components/panel-section";
import { Button } from "@/components/ui/button";
import { FieldGroup, SettingsRow } from "@/components/ui/field";
import { Switch } from "@/components/ui/switch";

const PageDemo = () => {
  const [hardware, setHardware] = useState(true);
  const [lowLatency, setLowLatency] = useState(false);
  return (
    <div className="bg-glass-content rounded-panel flex h-80 w-full max-w-xl overflow-hidden border">
      <Pane>
        <Toolbar title="Output" />
        <PaneBody className="@container/page flex flex-col">
          <PageHeader
            action={<Button variant="secondary">Test recording…</Button>}
            description="Quality for recordings and livestreams on this computer."
            title="Output"
          />
          <ConfigGrid className={CONFIG_GRID_PAIR}>
            <PanelSection
              description="1080p at 60 fps, 12 Mbps."
              title="Recording"
            >
              <FieldGroup variant="grouped">
                <SettingsRow label="Hardware encoder">
                  <Switch checked={hardware} onCheckedChange={setHardware} />
                </SettingsRow>
              </FieldGroup>
            </PanelSection>
            <PanelSection
              description="720p at 30 fps, 4.5 Mbps."
              title="Livestream"
            >
              <FieldGroup variant="grouped">
                <SettingsRow label="Low latency">
                  <Switch
                    checked={lowLatency}
                    onCheckedChange={setLowLatency}
                  />
                </SettingsRow>
              </FieldGroup>
            </PanelSection>
          </ConfigGrid>
        </PaneBody>
      </Pane>
    </div>
  );
};

export default PageDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/page
```

## Usage

```tsx
import {
  CONFIG_GRID_PAIR,
  ConfigGrid,
  Gallery,
  PageHeader,
  PageStack,
} from "@/components/page";
```

```tsx
<PaneBody className="@container/page">
  <PageHeader
    description="Quality for recordings and livestreams on this computer."
    title="Output"
  />
  <ConfigGrid>
    <PanelSection title="Recording">…</PanelSection>
    <PanelSection title="Livestream">…</PanelSection>
  </ConfigGrid>
</PaneBody>
```

Pages compose these instead of hand-rolling grids. A page follows its own width, never the window's: the pane body around it is a container, `@container/page`, and 940 px of it is the one layout breakpoint (a 1,024 px viewport counted the 208 px sidebar as page and squeezed two columns into 816 px). A form's own sub-grid uses `sm` and `md`.

| Archetype | Pages | Built with |
| --- | --- | --- |
| Config grid | Sources, Livestream, Output, Settings | A `ConfigGrid` of [Panel Sections](/docs/primitives/panel-section): one column, two from 940 px of page |
| Stack | One section, or a tab | A `PageStack` of Panel Sections |
| Gallery | Assets, Screens | A `Gallery` of picture cards |
| Browse | Library | A flush list or table in the pane body |
| Stage, Bench, Inspect | Studio, Scene, Health | Bespoke |

Don't add a max-width column or a hand-rolled grid. Don't put a page's actions in the toolbar either: they go at the end of the PageHeader's line, or in a section's header.

## Examples

### Gallery

Cards are only for objects with a picture: backgrounds, scenes, Buddies, library items. A Gallery fills its tracks by the width it has. `dense` packs 10 rem cards, for a picker inside a dialog. `rowsOfFive` holds a row to five cards, which may shrink to 11 rem so five fit the default window: ten cards read as two rows of five.

```tsx title="components/examples/page-gallery.tsx"
"use client";

import { useState } from "react";

import { Gallery } from "@/components/page";

const BACKGROUNDS = [
  "Studio wall",
  "Night city",
  "Bookshelf",
  "Gradient",
  "Forest",
  "Plain dark",
] as const;

const PageGallery = () => {
  const [chosen, setChosen] = useState<string>("Night city");
  return (
    <Gallery aria-label="Backgrounds" className="w-full max-w-xl" dense>
      {BACKGROUNDS.map((name) => (
        <button
          aria-pressed={chosen === name}
          className="rounded-row bg-foreground/4 aria-pressed:border-foreground/40 focus-visible:ring-ring flex flex-col overflow-hidden border text-left outline-none focus-visible:ring-2"
          key={name}
          onClick={() => setChosen(name)}
          type="button"
        >
          <span aria-hidden className="bg-video-ground aspect-video w-full" />
          <span className="text-meta truncate px-2 py-1.5">{name}</span>
        </button>
      ))}
    </Gallery>
  );
};

export default PageGallery;
```

### Two sections that fill the height

A tab of exactly two sections passes `CONFIG_GRID_PAIR` to its ConfigGrid. In two columns the grid fills the visible height, so the hairline between the columns runs the full height however short the tab is. Stacked, the rows keep their content height. The preview above does this.

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `px-gutter` | The PageHeader's 16 px sides |
| `@container/page` | The pane body the page sits in: the width the grid follows |
| `@min-[940px]/page:grid-cols-2` | The config grid's two columns |
| `@min-[940px]/page:[&>*:nth-child(odd)]:border-r` | The hairline between the columns |
| `CONFIG_GRID_PAIR` | `flex-1 content-start @min-[940px]/page:content-stretch @min-[940px]/page:[&>*]:border-b-0` |
| `data-slot` | `page-header`, `config-grid`, `gallery`, `page-stack` |

## Accessibility

The toolbar already shows the page's name as its `h1`, so PageHeader's `title` is a visually hidden `h2` for assistive tech. Its description is plain text. A Gallery is only a grid: give it an `aria-label`, and make each card a button, with `aria-pressed` when the gallery is a choice.

## API reference

### PageHeader

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | The page's name, for assistive tech. |
| `description` | `ReactNode` | — | The flush intro line. |
| `action` | `ReactNode` | — | Actions at the end of the line, never in the toolbar. |
| `media` | `ReactNode` | — | A page's own mark, leading the line. |
| `className` | `string` | — | — |

### ConfigGrid and PageStack

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | Panel Sections. |
| `className` | `string` | — | CONFIG_GRID_PAIR on a ConfigGrid of two. |

### Gallery

Every `div` attribute, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `dense` | `boolean` | `false` | 10 rem cards, for a picker in a dialog. |
| `rowsOfFive` | `boolean` | `false` | At most five cards a row, never narrower than 11 rem. |

# Pane (/docs/primitives/pane)

```tsx title="components/examples/pane-demo.tsx"
"use client";

import { CameraIcon, DisplayIcon, MicrophoneIcon } from "@/components/icons";
import { GroupedList, ListRow } from "@/components/list-row";
import { PageStack } from "@/components/page";
import { Pane, PaneBody, Toolbar } from "@/components/pane";
import { PanelSection } from "@/components/panel-section";
import { Button } from "@/components/ui/button";

const PaneDemo = () => (
  <div className="bg-glass-content rounded-panel flex h-80 w-full max-w-xl overflow-hidden border">
    <Pane>
      <Toolbar title="Sources" />
      <PaneBody>
        <PageStack>
          <PanelSection
            action={<Button variant="secondary">Add source…</Button>}
            description="What the Studio can capture."
            title="Video"
          >
            <GroupedList aria-label="Video sources">
              <ListRow
                context="Built-in"
                icon={<CameraIcon />}
                meta="In use"
                title="FaceTime HD Camera"
              />
              <ListRow
                context="Display 1"
                icon={<DisplayIcon />}
                meta="1920 × 1080"
                title="Screen"
              />
            </GroupedList>
          </PanelSection>
          <PanelSection description="Mixed into every scene." title="Audio">
            <GroupedList aria-label="Audio sources">
              <ListRow
                context="USB"
                icon={<MicrophoneIcon />}
                meta="In use"
                title="Shure MV7"
              />
              <ListRow
                context="Built-in"
                icon={<MicrophoneIcon />}
                meta="Off"
                title="MacBook Pro Microphone"
              />
            </GroupedList>
          </PanelSection>
        </PageStack>
      </PaneBody>
    </Pane>
  </div>
);

export default PaneDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/pane
```

## Usage

```tsx
import {
  PANE_OWNS_SCROLL,
  Pane,
  PaneBody,
  PaneStrip,
  Toolbar,
} from "@/components/pane";
```

```tsx
<Pane>
  <Toolbar title="Sources" />
  <PaneBody>…</PaneBody>
</Pane>
```

Use it for every page's chrome: a Pane, a Toolbar with the title, a PaneBody. Panes are flush, split by 1 px hairlines, and nothing inside a window floats. A tab list or a filter bar pinned under the toolbar is a PaneStrip.

Don't put buttons in the toolbar: actions live with the content they act on, in a section's header, a filter bar or the [PageHeader](/docs/primitives/page) line. Don't nest a second scroll container inside PaneBody either: a page that needs its own says so with `PANE_OWNS_SCROLL`.

## Anatomy

```tsx
<Pane>
  <Toolbar title />
  <PaneBody>
    {/* a page that pins a strip owns its scroll */}
    <div {...PANE_OWNS_SCROLL}>
      <PaneStrip />
      {/* the region that scrolls */}
    </div>
  </PaneBody>
</Pane>
```

## Examples

### A pinned strip

A page that pins a strip under the toolbar spreads `PANE_OWNS_SCROLL` on its root. PaneBody sees it, stops scrolling and turns into a flex column, so only the region under the strip scrolls. The shell keeps no list of such pages. [Page Tabs](/docs/primitives/page-tabs) does all of this for a page with tabs.

```tsx title="components/examples/pane-strip.tsx"
"use client";

import { useState } from "react";

import { LivestreamIcon, VideoFileIcon } from "@/components/icons";
import { GroupedList, ListRow } from "@/components/list-row";
import {
  PANE_OWNS_SCROLL,
  Pane,
  PaneBody,
  PaneStrip,
  Toolbar,
} from "@/components/pane";
import { SegmentedControl } from "@/components/ui/segmented-control";

type Kind = "all" | "recording" | "livestream";

const KINDS = [
  { label: "All", value: "all" },
  { label: "Recordings", value: "recording" },
  { label: "Livestreams", value: "livestream" },
] as const;

const SESSIONS = [
  { date: "Today", kind: "livestream", length: "1:12:40", title: "Friday Q&A" },
  { date: "Today", kind: "recording", length: "08:14", title: "Intro take 3" },
  {
    date: "Yesterday",
    kind: "recording",
    length: "21:05",
    title: "Tutorial: scenes",
  },
  {
    date: "Monday",
    kind: "livestream",
    length: "2:03:11",
    title: "Speedrun night",
  },
  {
    date: "Monday",
    kind: "recording",
    length: "04:52",
    title: "Thumbnail clips",
  },
  {
    date: "Oct 24",
    kind: "livestream",
    length: "58:30",
    title: "Community hangout",
  },
] as const;

const PaneStripExample = () => {
  const [kind, setKind] = useState<Kind>("all");
  const shown = SESSIONS.filter(
    (session) => kind === "all" || session.kind === kind
  );
  return (
    <div className="bg-glass-content rounded-panel flex h-80 w-full max-w-xl overflow-hidden border">
      <Pane>
        <Toolbar title="Library" />
        <PaneBody>
          {/* The page owns its scroll: the strip stays, the list scrolls. */}
          <div {...PANE_OWNS_SCROLL} className="flex min-h-0 flex-1 flex-col">
            <PaneStrip>
              <SegmentedControl
                aria-label="Show"
                onValueChange={setKind}
                options={KINDS}
                size="sm"
                value={kind}
              />
            </PaneStrip>
            <div className="p-gutter min-h-0 flex-1 overflow-y-auto overscroll-contain">
              <GroupedList aria-label="Sessions">
                {shown.map((session) => (
                  <ListRow
                    as="button"
                    context={session.date}
                    icon={
                      session.kind === "livestream" ? (
                        <LivestreamIcon />
                      ) : (
                        <VideoFileIcon />
                      )
                    }
                    key={session.title}
                    meta={session.length}
                    title={session.title}
                  />
                ))}
              </GroupedList>
            </div>
          </div>
        </PaneBody>
      </Pane>
    </div>
  );
};

export default PaneStripExample;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `h-toolbar` | The 40 px toolbar |
| `px-gutter` | The 16 px sides of the toolbar and the strip |
| `border-b`, `border-border` | The hairline under the toolbar and the strip |
| `WINDOW_TITLE_CLASS` | The title recipe, 14 px / 600 primary text, shared with [Window Frame](/docs/primitives/window-frame) |
| `[-webkit-app-region:drag]` | The toolbar moves the window in Electron |
| `overflow-y-auto`, `overscroll-contain` | PaneBody's scroll |
| `data-pane-scroll="own"` | A page that owns its scroll, from `PANE_OWNS_SCROLL` |
| `data-slot` | `pane`, `toolbar`, `pane-body`, `pane-strip` |

## Accessibility

The toolbar's title is the page's `h1`, focusable by script only (`tabIndex={-1}`). After keyboard navigation to a page, move the focus to it: the new page is announced and the next `Tab` starts at its top.

The drag band does nothing in a browser. In Electron it moves the window, and any control on a drag band needs `[-webkit-app-region:no-drag]` to take clicks; the toolbar holds none.

## API reference

### Toolbar

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `ReactNode` | — | The page's title, as its h1. |
| `className` | `string` | — | — |

### Pane

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | A Toolbar and a PaneBody. |
| `className` | `string` | — | — |

### PaneBody

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `scroll` | `boolean` | `true` | false for a body that always owns its scroll: a flex column that never scrolls. |
| `children` | `ReactNode` | — | — |
| `className` | `string` | — | — |

### PaneStrip

Every `div` attribute.

### Constants

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `PANE_OWNS_SCROLL` | `{ "data-pane-scroll": "own" }` | — | Spread it on a page's root when the page owns its scroll. |
| `WINDOW_TITLE_CLASS` | `string` | — | The one title recipe. |

# Panel Section (/docs/primitives/panel-section)

```tsx title="components/examples/panel-section-demo.tsx"
"use client";

import { useState } from "react";

import { FolderIcon, MarkerIcon } from "@/components/icons";
import { PanelSection } from "@/components/panel-section";
import { Button } from "@/components/ui/button";
import { FieldGroup, SettingsRow } from "@/components/ui/field";
import { Switch } from "@/components/ui/switch";

const PanelSectionDemo = () => {
  const [saveLocal, setSaveLocal] = useState(true);
  const [tracks, setTracks] = useState(false);
  const [markers, setMarkers] = useState(true);
  return (
    <div className="bg-glass-content rounded-panel w-full max-w-xl overflow-hidden border">
      <PanelSection
        action={
          <Button variant="secondary">
            <FolderIcon data-icon="inline-start" />
            Choose folder…
          </Button>
        }
        description="Recordings save to ~/Movies/Videorc."
        title="Recording"
      >
        <FieldGroup variant="grouped">
          <SettingsRow
            description="Keep a copy on this computer while you stream."
            label="Save local recording"
          >
            <Switch checked={saveLocal} onCheckedChange={setSaveLocal} />
          </SettingsRow>
          <SettingsRow
            description="One track per microphone, for editing later."
            label="Separate audio tracks"
          >
            <Switch checked={tracks} onCheckedChange={setTracks} />
          </SettingsRow>
        </FieldGroup>
      </PanelSection>
      <PanelSection
        action={
          <Switch
            aria-label="Markers"
            checked={markers}
            onCheckedChange={setMarkers}
          />
        }
        description="Press M while you record to mark a moment you want to find again."
        icon={MarkerIcon}
        title="Markers"
      />
    </div>
  );
};

export default PanelSectionDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/panel-section
```

## Usage

```tsx
import { PanelSection } from "@/components/panel-section";
```

```tsx
<PanelSection
  description="Recordings save to ~/Movies/Videorc."
  title="Recording"
>
  …
</PanelSection>
```

Use it for every section of a page or a pane: Settings, Output, Sources, the inspector. Rules a streamer needs, such as limits or what Premium adds, go in its `description`, never in a footnote.

Don't put a border, a background, a radius or a shadow around page content, and don't put a card inside a section. Sections are flush and split by hairlines.

## Anatomy

```tsx
<PanelSection title description icon action headingLevel>
  {/* content */}
</PanelSection>
```

## Examples

### Nested sections

A section under another section's heading passes `headingLevel={3}`, so the outline reads h1 (the toolbar's title), h2, h3. A section with no children is only its header: a title, what it says, and its action.

```tsx title="components/examples/panel-section-nested.tsx"
"use client";

import { useState } from "react";

import { CameraIcon } from "@/components/icons";
import { PanelSection } from "@/components/panel-section";
import { Field, FieldLabel } from "@/components/ui/field";
import { SegmentedControl } from "@/components/ui/segmented-control";
import { Switch } from "@/components/ui/switch";

type Fit = "fill" | "fit";

const FITS = [
  { label: "Fill", value: "fill" },
  { label: "Fit", value: "fit" },
] as const;

const PanelSectionNested = () => {
  const [visible, setVisible] = useState(true);
  const [fit, setFit] = useState<Fit>("fill");
  return (
    <div className="bg-glass-content rounded-panel w-full max-w-sm overflow-hidden border">
      <PanelSection
        action={
          <Switch
            aria-label="Show camera"
            checked={visible}
            onCheckedChange={setVisible}
          />
        }
        description="FaceTime HD Camera"
        icon={CameraIcon}
        title="Camera"
      />
      <PanelSection
        description="Drag the camera on the stage, or nudge it with the arrow keys."
        headingLevel={3}
        title="Placement"
      />
      <PanelSection headingLevel={3} title="Lens">
        <Field>
          <FieldLabel>Fit</FieldLabel>
          <SegmentedControl onValueChange={setFit} options={FITS} value={fit} />
        </Field>
      </PanelSection>
    </div>
  );
};

export default PanelSectionNested;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `p-gutter` | 16 px of padding |
| `border-b`, `border-border` | The hairline to the next section; the last one has none |
| `text-section` | The 13 px / 600 title |
| `text-meta`, `text-muted-foreground` | The 12 px description, in the secondary tier |
| `h-5` | The action's line, as tall as the title, so a 28 px button or a switch centres on it |
| `data-slot` | `panel-section`, `panel-section-header`, `panel-section-description`, `panel-section-action`, `panel-section-content` |
| `data-*` | Any `data-` prop lands on the section, for tests and probes |

## Accessibility

The title is an `h2` under the toolbar's `h1`, or an `h3` with `headingLevel={3}`. A section without a title has no heading, for when the layout around it already names it. A switch or an icon button in `action` needs its own `aria-label`.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | The section's heading. Leave it out for padded content alone. |
| `description` | `ReactNode` | — | A 12 px line under the title. |
| `icon` | `AppIcon` | — | A 16 px duotone icon before the title. |
| `action` | `ReactNode` | — | Controls for the whole section, on the title's line. |
| `headingLevel` | `2 \| 3` | `2` | 3 for a section under another section's heading. |
| `contentClassName` | `string` | — | Classes for the content box. |
| `children` | `ReactNode` | — | The content. Without it, the section is only its header. |

# Pin Window Button (/docs/primitives/pin-window-button)

```tsx title="components/examples/pin-window-button-demo.tsx"
"use client";

import { useState } from "react";

import { PinWindowButton } from "@/components/pin-window-button";
import { WindowHeader } from "@/components/window-frame";

const PinWindowButtonDemo = () => {
  const [pinned, setPinned] = useState(false);
  return (
    <div className="bg-glass-content rounded-panel w-full max-w-sm overflow-hidden border">
      <WindowHeader platform="linux" title="Notes">
        <PinWindowButton onPinnedChange={setPinned} pinned={pinned} />
      </WindowHeader>
      <p className="p-gutter text-muted-foreground text-sm select-text">
        {pinned
          ? "Notes stays over other apps, so it's there while you record."
          : "Pin Notes to keep it over other apps while you record."}
      </p>
    </div>
  );
};

export default PinWindowButtonDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/pin-window-button
```

## Usage

```tsx
import { PinWindowButton } from "@/components/pin-window-button";
```

```tsx
<PinWindowButton onPinnedChange={setAlwaysOnTop} pinned={alwaysOnTop} />
```

The window's state comes in through props. In Electron, ask the main process to call `setAlwaysOnTop` on the window, and pass back what it reports as `pinned`.

Use it for the one Keep on top control in a detached window: Notes, the Captions reader, Stream Manager. The header look sits in a [Window Header](/docs/primitives/window-frame).

Don't rename it per window or swap its icon, and don't put it in the main window.

## Examples

### In a status bar

`variant="status-bar"` is a [Status Bar Action](/docs/primitives/status-bar-action), for a window whose title row stays bare, such as Stream Manager.

```tsx title="components/examples/pin-window-button-status-bar.tsx"
"use client";

import { useState } from "react";

import { PinWindowButton } from "@/components/pin-window-button";
import { StatusBar } from "@/components/status-bar";

const PinWindowButtonStatusBar = () => {
  const [pinned, setPinned] = useState(true);
  return (
    <div className="bg-glass-content rounded-panel w-full max-w-sm overflow-hidden border">
      <StatusBar leading="Stream Manager">
        <PinWindowButton
          onPinnedChange={setPinned}
          pinned={pinned}
          variant="status-bar"
        />
      </StatusBar>
    </div>
  );
};

export default PinWindowButtonStatusBar;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `Button` `ghost`, `size="icon"` | The header look |
| `text-muted-foreground` | Unpinned reads a tier quieter; hover brightens it |
| `PinIcon` | Regular while unpinned, filled while pinned |
| `[-webkit-app-region:no-drag]` | Clickable on a header's drag band |
| `data-testid="pin-window-button"` | On the button, in either look |

## Keyboard

| Key              | Action                    |
| ---------------- | ------------------------- |
| `Enter`, `Space` | Pins or unpins the window |

## Accessibility

It's named "Keep on top" (`PIN_WINDOW_LABEL`) in every window, with `aria-pressed` saying whether the window is pinned. A tooltip shows the name on hover, never a native `title`. Base UI's Tooltip needs no provider, so the button works in a window that has none; under one, it joins that window's delay group.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `pinned` | `boolean` | — | The window stays over other apps. |
| `onPinnedChange` | `(pinned: boolean) => void` | — | Called with the state a click asks for. |
| `variant` | `"header" \| "status-bar"` | `"header"` | — |
| `className` | `string` | — | — |

`PIN_WINDOW_LABEL` is the control's one name, `"Keep on top"`.

# Power Slider (/docs/primitives/power-slider)

```tsx title="components/examples/power-slider-demo.tsx"
"use client";

import { useState } from "react";

import { WaveformIcon } from "@/components/icons";
import { PowerSlider } from "@/components/power-slider";

const PowerSliderDemo = () => {
  const [value, setValue] = useState(60);
  return (
    <PowerSlider
      className="w-full max-w-sm"
      defaultValue={40}
      icon={WaveformIcon}
      label="Noise cleanup"
      max={100}
      min={0}
      onChange={setValue}
      rangeHints
      status={{ label: "Beta" }}
      suffix="%"
      value={value}
    />
  );
};

export default PowerSliderDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/power-slider
```

It installs `lib/power-slider-math.ts`, the value math, beside the component.

## Usage

```tsx
import { PowerSlider } from "@/components/power-slider";
```

```tsx
<PowerSlider
  defaultValue={40}
  label="Noise cleanup"
  max={100}
  min={0}
  onChange={setPreview}
  onCommit={saveNoiseCleanup}
  suffix="%"
  value={value}
/>
```

`onChange` is the live preview, fired while dragging and on every key: keep it cheap. `onCommit` fires on release, on a key, on reset and on a typed number, so write the expensive update (the engine, a saved setting) there and a drag can't flood it. Without `onCommit`, `onChange` does both.

Use it for a setting with a range, a unit and a default: noise cleanup, gain, exposure, delays. Use a plain [Slider](/docs/components/slider) for a scrubber or a level with no label row. Don't ship a slider with nothing behind it.

## Examples

### Bipolar, with marks

`bipolar` signs positive values ("+0.5 EV"). `marks` puts labelled points under the track; `rangeHints` puts the ends there instead (and the middle, when bipolar).

```tsx title="components/examples/power-slider-bipolar.tsx"
"use client";

import { useState } from "react";

import { CameraIcon } from "@/components/icons";
import { PowerSlider } from "@/components/power-slider";

const PowerSliderBipolar = () => {
  const [value, setValue] = useState(0.5);
  return (
    <PowerSlider
      bipolar
      className="w-full max-w-sm"
      defaultValue={0}
      icon={CameraIcon}
      label="Exposure"
      marks={[
        { label: "Darker", value: -2 },
        { label: "Auto", value: 0 },
        { label: "Brighter", value: 2 },
      ]}
      max={2}
      min={-2}
      onChange={setValue}
      step={0.1}
      suffix=" EV"
      value={value}
    />
  );
};

export default PowerSliderBipolar;
```

### Typed numbers and disabled

`numericInput` replaces the readout with a field: <kbd>Enter</kbd> or leaving the field commits, clamped and snapped to the step; <kbd>Esc</kbd> drops the draft. A disabled slider says why under the track, and `status` adds a chip after the label.

```tsx title="components/examples/power-slider-numeric.tsx"
"use client";

import { useState } from "react";

import { MicrophoneIcon } from "@/components/icons";
import { PowerSlider } from "@/components/power-slider";

const noop = () => {
  // Disabled: it never changes.
};

const PowerSliderNumeric = () => {
  const [delay, setDelay] = useState(120);
  const [committed, setCommitted] = useState(120);
  return (
    <div className="flex w-full max-w-sm flex-col gap-6">
      <PowerSlider
        defaultValue={0}
        icon={MicrophoneIcon}
        label="Mic delay"
        largeStep={100}
        max={1000}
        min={0}
        numericInput
        onChange={setDelay}
        onCommit={setCommitted}
        step={10}
        suffix=" ms"
        value={delay}
      />
      <p className="text-muted-foreground text-meta">
        Saved: {committed} ms. The live value follows the drag; the saved one
        changes on release.
      </p>
      <PowerSlider
        disabled
        disabledReason="Turn on a microphone to adjust its gain."
        label="Gain"
        max={24}
        min={0}
        onChange={noop}
        status={{ label: "No microphone", tone: "warning" }}
        suffix=" dB"
        value={0}
      />
    </div>
  );
};

export default PowerSliderNumeric;
```

## The value math

`lib/power-slider-math.ts` is pure and framework-free, so the exact clamping, stepping and formatting the slider relies on is tested directly.

| Function | What it does |
| --- | --- |
| `clampToRange(value, range)` | Clamps into the range and snaps to the step grid from `min`, without floating-point drift. NaN reads as `min` |
| `stepValue(value, range, direction, { large?, largeStep? })` | One keyboard move; the large one is 10 steps unless given |
| `parseNumericInput(raw, range)` | A typed number, clamped and snapped, or null for blank and non-numeric input |
| `formatValue(value, { suffix?, decimals?, bipolar?, step? })` | The readout, with decimals from the step and a "+" on a positive bipolar value |
| `valuePercent(value, range)` | Where a value sits along the track, 0 to 100 |

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `chrome-fill`, `chrome-bead` | The range and the thumb, from [Slider](/docs/components/slider) |
| `text-label` | The marks under the track |
| `--mark` | Each mark's place along the track |
| `data-slot="power-slider"` | The whole control |

## Keyboard

| Key | Action |
| --- | --- |
| <kbd>←</kbd> <kbd>→</kbd> <kbd>↑</kbd> <kbd>↓</kbd> | Moves by one step |
| <kbd>Shift</kbd> + arrow, <kbd>Page Up</kbd> <kbd>Page Down</kbd> | Moves by `largeStep` |
| <kbd>Home</kbd> <kbd>End</kbd> | Goes to `min` or `max` |

A double-click on the track resets to `defaultValue`; the reset button is the keyboard way.

## Accessibility

The thumb is named by the label. The reset button is named `Reset {label}` and the typed field `{label} value`. A disabled slider's reason is visible text under it.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | — | — |
| `value` | `number` | — | — |
| `min` | `number` | — | — |
| `max` | `number` | — | — |
| `onChange` | `(value: number) => void` | — | The live preview. |
| `onCommit` | `(value: number) => void` | `onChange` | Release, keys, reset and typed numbers. |
| `step` | `number` | `1` | — |
| `largeStep` | `number` | `step × 10` | Shift+arrow and Page Up/Down. |
| `defaultValue` | `number` | — | Enables reset once the value drifts. |
| `suffix` | `string` | — | The unit: "%", " ms", " dB". |
| `decimals` | `number` | — | From step when unset. |
| `bipolar` | `boolean` | `false` | Signs positives: "+12". |
| `marks` | `{ value: number; label?: string }[]` | — | — |
| `rangeHints` | `boolean` | `false` | The ends under the track. |
| `numericInput` | `boolean` | `false` | A typed number for the readout. |
| `icon` | `AppIcon` | — | — |
| `status` | `{ label: string; tone?: "default" \| "success" \| "warning" \| "destructive" }` | — | A chip after the label. |
| `disabled` | `boolean` | `false` | — |
| `disabledReason` | `string` | — | Why it's disabled, under the track. |
| `className` | `string` | — | — |

# Record Button (/docs/primitives/record-button)

```tsx title="components/examples/record-button-demo.tsx"
"use client";

import { useEffect, useRef, useState } from "react";

import { RecordButton } from "@/components/record-button";
import type { RecordButtonState } from "@/components/record-button";

// How long a pretend backend takes to start a recording and to finish one.
const START_TAKES_MS = 600;
const STOP_TAKES_MS = 900;

const RecordButtonDemo = () => {
  const [state, setState] = useState<RecordButtonState>("idle");
  const pending = useRef<ReturnType<typeof setTimeout>>(undefined);
  useEffect(() => () => clearTimeout(pending.current), []);

  // A busy button takes no click, so only idle and running get here.
  const toggle = () => {
    const starting = state === "idle";
    setState(starting ? "starting" : "stopping");
    pending.current = setTimeout(
      () => setState(starting ? "running" : "idle"),
      starting ? START_TAKES_MS : STOP_TAKES_MS
    );
  };

  return <RecordButton onClick={toggle} size="lg" state={state} />;
};

export default RecordButtonDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/record-button
```

It brings [Button](/docs/components/button) with it.

## Usage

```tsx
import { RecordButton } from "@/components/record-button";
```

```tsx
<RecordButton onClick={toggleRecording} state={session} />
```

`state` is where the session stands, and comes in from your app: `idle`, `starting` after the click, `running` once it records or streams, and `stopping` while it finishes. The button picks its glyph, lights up and says each state's words. Pass your own words for any state in `labels` ("End livestream" while on air, "Force stop" after a stop that drags on).

```tsx
<RecordButton labels={{ running: "End livestream" }} state={session} />
```

Every state's words are laid out in the same spot and only the current one shows, so the button is as wide as its longest words and never changes width as the session moves on.

Use it for Record and the button that stops the session, and nothing else: lit red only ever means record or live. Delete stays a `destructive` Button, and Go Live… stays the chrome primary beside it.

## Examples

### States

Starting and stopping answer from the click: the button is lit, takes no click, keeps its focus and doesn't dim. Only a running session's glow breathes. Blocked is a disabled button, flat and dimmed; say why with [Disabled reason](/docs/components/disabled-reason).

```tsx title="components/examples/record-button-states.tsx"
import { RecordButton } from "@/components/record-button";
import type { RecordButtonState } from "@/components/record-button";

const STATES: {
  caption: string;
  disabled?: boolean;
  running?: string;
  state: RecordButtonState;
}[] = [
  { caption: "Idle", state: "idle" },
  { caption: "Starting", state: "starting" },
  { caption: "Recording", state: "running" },
  { caption: "Live", running: "End livestream", state: "running" },
  { caption: "Stopping", state: "stopping" },
  { caption: "Blocked", disabled: true, state: "idle" },
];

const RecordButtonStates = () => (
  <div className="grid grid-cols-[auto_auto_auto] items-center gap-x-6 gap-y-3">
    {STATES.map(({ caption, disabled, running, state }) => (
      <div className="contents" key={caption}>
        <span className="text-meta text-muted-foreground">{caption}</span>
        <RecordButton
          disabled={disabled}
          labels={{ running }}
          size="lg"
          state={state}
        />
        <RecordButton disabled={disabled} labels={{ running }} state={state} />
      </div>
    ))}
  </div>
);

export default RecordButtonStates;
```

### In the transport

The Studio's transport puts Record, with its Space key, beside Go Live…. While a session runs, one stop button takes the row. While Go Live… runs its checks, Record is off.

```tsx title="components/examples/record-button-transport.tsx"
"use client";

import { useEffect, useRef, useState } from "react";
import type { ReactNode } from "react";

import { LivestreamIcon } from "@/components/icons";
import { RecordButton } from "@/components/record-button";
import type { RecordButtonState } from "@/components/record-button";
import { Button } from "@/components/ui/button";
import { ShortcutKeys } from "@/components/ui/shortcut-keys";

// How long a pretend backend takes to start a session and to finish one.
const START_TAKES_MS = 600;
const STOP_TAKES_MS = 900;

/**
 * The Studio's transport: Record beside Go Live…, then one stop button. The
 * same RecordButton stays mounted from Record to Stop, so keyboard focus
 * stays on it through the whole session.
 */
const RecordButtonTransport = () => {
  const [state, setState] = useState<RecordButtonState>("idle");
  const [live, setLive] = useState(false);
  const pending = useRef<ReturnType<typeof setTimeout>>(undefined);
  useEffect(() => () => clearTimeout(pending.current), []);

  const settle = (next: RecordButtonState, ms: number) => {
    pending.current = setTimeout(() => setState(next), ms);
  };
  const start = (livestream: boolean) => {
    setLive(livestream);
    setState("starting");
    settle("running", START_TAKES_MS);
  };
  const stop = () => {
    setState("stopping");
    settle("idle", STOP_TAKES_MS);
  };

  const idle = state === "idle";
  // While Go Live… runs its checks, Record is off, as in Videorc: only the
  // button that was clicked answers.
  const checking = state === "starting" && live;
  const session = state === "running" || state === "stopping";
  // Record shows its key, and a livestream ends in its own words. The
  // button keeps one width through them all.
  const labels = {
    idle: (
      <>
        Record
        <ShortcutKeys accelerator="Space" className="ml-0.5" />
      </>
    ),
    running: live ? "End livestream" : undefined,
  };
  // Go Live… says "Checking…" from its click, as in Videorc.
  let goLive: ReactNode = null;
  if (checking) {
    goLive = (
      <Button className="flex-1" disabled size="lg">
        <LivestreamIcon data-icon="inline-start" weight="fill" />
        Checking…
      </Button>
    );
  } else if (!session) {
    goLive = (
      <Button
        className="flex-1"
        disabled={!idle}
        onClick={() => start(true)}
        size="lg"
      >
        <LivestreamIcon data-icon="inline-start" weight="fill" />
        Go Live…
      </Button>
    );
  }
  return (
    <div className="flex w-80 gap-2">
      <RecordButton
        className="flex-1"
        disabled={checking}
        labels={labels}
        onClick={idle ? () => start(false) : stop}
        size="lg"
        state={checking ? "idle" : state}
      />
      {goLive}
    </div>
  );
};

export default RecordButtonTransport;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `chrome-led` | The material, on Button's `record` variant |
| `--chrome-led-off-stops`, `--chrome-led-stops` | The metal's bands, idle and lit |
| `--chrome-led-hi`, `--chrome-led-lo` | The light along its top edge and the shade along its foot |
| `--chrome-led-glow` | The glow around it while the session runs |
| `data-lit` | Lights it: set from `starting` on |
| `data-state` | `idle`, `starting`, `running` or `stopping` |

It's polished the way the default button's chrome is: a bright band, a dark horizon just below the middle and the light coming back at the foot. Every stop keeps the white label at 4.5:1 or more in both themes, so the shine is in the bands, never a brighter face. The glow is a layer of its own that breathes on opacity alone, so a session that runs for hours never repaints the button. Under reduced motion, it holds steady. Increase Contrast adds an edge around it.

## Keyboard

| Key              | Action                      |
| ---------------- | --------------------------- |
| `Enter`, `Space` | Starts or stops the session |

A shortcut for Record belongs to the page, not to the button. Show it inside with [Shortcut Keys](/docs/components/shortcut-keys).

## Accessibility

It's a one-shot action whose words change ("Record", then "Stop recording"), so it takes no `aria-pressed`. While starting or stopping, it's `aria-disabled` and stays focusable, so keyboard focus isn't lost under the user's hands. Announce the session's state in a status region, such as a [Status Badge](/docs/primitives/status-badge) with `role="status"`, not on the button.

## API reference

Every [Button](/docs/components/button) prop except `variant` and `children`, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state` | `"idle" \| "starting" \| "running" \| "stopping"` | `"idle"` | Where the session stands. |
| `labels` | `Partial<Record<state, ReactNode>>` | — | Your words for any state. Defaults to "Record", "Stop recording" and "Stopping…". |
| `disabled` | `boolean` | `false` | A start is blocked. Busy states disable the button for you. |

`RECORD_BUTTON_LABELS` holds each state's default words.

# Section Label (/docs/primitives/section-label)

```tsx title="components/examples/section-label-demo.tsx"
"use client";

import { useState } from "react";

import {
  AssetsIcon,
  LivestreamIcon,
  SceneIcon,
  SourcesIcon,
  StudioIcon,
} from "@/components/icons";
import { ListRow } from "@/components/list-row";
import { SectionLabel } from "@/components/section-label";
import { ShortcutKeys } from "@/components/ui/shortcut-keys";

const SETUP = [
  { accelerator: "CmdOrCtrl+2", icon: SourcesIcon, name: "Sources" },
  { accelerator: "CmdOrCtrl+3", icon: SceneIcon, name: "Scene" },
  { accelerator: "CmdOrCtrl+4", icon: AssetsIcon, name: "Assets" },
  { accelerator: "CmdOrCtrl+5", icon: LivestreamIcon, name: "Livestream" },
] as const;

const SectionLabelDemo = () => {
  const [page, setPage] = useState<string>("Sources");
  return (
    <nav
      aria-label="Pages"
      className="bg-glass-sidebar rounded-panel flex w-56 flex-col gap-3 border p-2"
    >
      <ListRow
        as="button"
        compact
        icon={<StudioIcon />}
        meta={<ShortcutKeys accelerator="CmdOrCtrl+1" variant="text" />}
        onClick={() => setPage("Studio")}
        selected={page === "Studio"}
        title="Studio"
      />
      <div className="flex flex-col gap-0.5">
        <SectionLabel as="h3" className="px-3 pb-1">
          Setup
        </SectionLabel>
        {SETUP.map(({ accelerator, icon: Icon, name }) => (
          <ListRow
            aria-current={page === name ? "page" : undefined}
            as="button"
            compact
            icon={<Icon />}
            key={name}
            meta={<ShortcutKeys accelerator={accelerator} variant="text" />}
            onClick={() => setPage(name)}
            selected={page === name}
            title={name}
          />
        ))}
      </div>
    </nav>
  );
};

export default SectionLabelDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/section-label
```

## Usage

```tsx
import { SectionLabel } from "@/components/section-label";
```

```tsx
<SectionLabel>Setup</SectionLabel>
```

Use it for the name over a group: the sidebar's "Setup", a block of fields in a dialog, a group of rows. A [grouped list](/docs/primitives/list-row) draws one for you with its `label`. A group of one row carries no label.

Don't use it for a section's header: that's [Panel Section](/docs/primitives/panel-section)'s 13 px title. Don't put anything a streamer must read in it either: the tertiary tier is for labels, and essential copy uses the secondary tier.

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `text-label` | 11 px at weight 600 |
| `text-subtle` | The tertiary text tier |
| `SECTION_LABEL` | The recipe as a class string, for an element that can't be a SectionLabel |
| `data-slot="section-label"` | The label |

## Accessibility

It renders a `<span>`, so it adds nothing to the document outline. Pass `as="h3"` or `as="h4"` when the label names a region someone would jump to by heading, such as a sidebar group, and `as="p"` or `as="div"` for a block.

## API reference

Every HTML attribute, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `"span" \| "div" \| "p" \| "h3" \| "h4"` | `"span"` | The element it renders. |

`SECTION_LABEL` is the recipe's class string: `text-label font-semibold text-subtle`.

# Status Badge (/docs/primitives/status-badge)

```tsx title="components/examples/status-badge-demo.tsx"
"use client";

import { StatusBadge } from "@/components/status-badge";

const StatusBadgeDemo = () => (
  <div className="flex flex-wrap items-center gap-2">
    <StatusBadge tone="good" value="Connected" />
    <StatusBadge tone="warn" value="Reconnecting" />
    <StatusBadge tone="error" value="Upload failed" />
    <StatusBadge tone="live" value="On air" />
    <StatusBadge value="Idle" />
  </div>
);

export default StatusBadgeDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/status-badge
```

It brings [Status word](/docs/hooks/status-word) with it, for the tones and the raw-value guard.

## Usage

```tsx
import { StatusBadge } from "@/components/status-badge";
```

```tsx
<StatusBadge label="Chat" tone="good" value="Connected" />
```

`value` is a word in sentence case, already mapped from its state ("Reconnecting", "On air"). The badge never recases it, and a raw value such as `device-missing` throws under test.

Use it for a state that needs a chip: a connection, a destination, a device. Don't color the words, and don't hand-roll a rounded span for a status: that's this or a [Badge](/docs/components/badge).

## Examples

### Labels and icons

`label` adds a muted word before the value. A leading `icon` replaces the dot and takes the tone, except on `error` and `live`, where the whole chip carries it.

```tsx title="components/examples/status-badge-label.tsx"
"use client";

import {
  CameraIcon,
  ChatIcon,
  MicrophoneIcon,
  YoutubeIcon,
} from "@/components/icons";
import { StatusBadge } from "@/components/status-badge";

const StatusBadgeLabel = () => (
  <div className="flex flex-wrap items-center gap-2">
    <StatusBadge label="Chat" tone="good" value="Read and write" />
    <StatusBadge label="Captions" tone="warn" value="Delayed" />
    <StatusBadge icon={CameraIcon} tone="warn" value="Needs permission" />
    <StatusBadge icon={MicrophoneIcon} tone="good" value="Ready" />
    <StatusBadge icon={YoutubeIcon} tone="live" value="On air" />
    <StatusBadge
      icon={ChatIcon}
      label="Twitch"
      tone="error"
      value="Disconnected"
    />
  </div>
);

export default StatusBadgeLabel;
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `glass-chip`, `glass-dot` | The chip and its glowing 6 px dot |
| `glass-chip-tinted` | The emphasis chip for `error` and `live` |
| `tone-success`, `tone-warning`, `tone-destructive`, `tone-live`, `tone-neutral` | The tone, through `--chip-tone` |
| `data-tone` | `good`, `warn`, `error`, `live` or `neutral` |

## Accessibility

The badge is text: the value is read as it's written, and the dot and the icon are hidden from screen readers. The tone is never the only signal, because the word says it too.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | A word in sentence case, already mapped from its state. |
| `label` | `string` | — | A muted word before the value. |
| `tone` | `"good" \| "warn" \| "error" \| "live" \| "neutral"` | `"neutral"` | — |
| `icon` | `AppIcon` | — | Replaces the dot and takes the tone. |
| `className` | `string` | — | — |

`StatusTone` and `STATUS_TONE_CLASS` are re-exported from [Status word](/docs/hooks/status-word), for a readout that draws its own status in the same tones.

# Status Bar Action (/docs/primitives/status-bar-action)

```tsx title="components/examples/status-bar-action-demo.tsx"
"use client";

import { useState } from "react";

import { ClipIcon, PauseIcon, PreviewIcon } from "@/components/icons";
import { StatusBar } from "@/components/status-bar";
import { StatusBarAction } from "@/components/status-bar-action";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuLabel,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu";

const LENGTHS = ["15", "30", "60"] as const;

const StatusBarActionDemo = () => {
  const [paused, setPaused] = useState(false);
  const [length, setLength] = useState<string>("30");
  const [clips, setClips] = useState(0);
  return (
    <div className="bg-glass-content rounded-panel flex w-full max-w-xl flex-col overflow-hidden border">
      <p
        aria-live="polite"
        className="px-gutter text-muted-foreground py-6 text-sm"
      >
        {clips > 0
          ? `Saved ${clips === 1 ? "a clip" : `${clips} clips`} of the last ${length} seconds to Library.`
          : "Chat from YouTube and Twitch shows up here while you're live."}
      </p>
      <StatusBar leading="2 destinations">
        <StatusBarAction
          accelerator="CmdOrCtrl+Shift+C"
          hint={`Save the last ${length} seconds to Library`}
          icon={<ClipIcon aria-hidden />}
          label="Save a clip"
          onClick={() => setClips((count) => count + 1)}
          text="Clip"
        />
        <DropdownMenu>
          <DropdownMenuTrigger
            render={
              <StatusBarAction label="Clip length" text={`${length} s`} />
            }
          />
          <DropdownMenuContent align="end" className="w-40" side="top">
            <DropdownMenuLabel>Clip length</DropdownMenuLabel>
            <DropdownMenuRadioGroup
              onValueChange={(value: string) => setLength(value)}
              value={length}
            >
              {LENGTHS.map((seconds) => (
                <DropdownMenuRadioItem key={seconds} value={seconds}>
                  {seconds} seconds
                </DropdownMenuRadioItem>
              ))}
            </DropdownMenuRadioGroup>
          </DropdownMenuContent>
        </DropdownMenu>
        <StatusBarAction
          icon={<PauseIcon aria-hidden />}
          label="Pause chat scrolling"
          onClick={() => setPaused((value) => !value)}
          pressed={paused}
        />
        <StatusBarAction
          icon={<PreviewIcon aria-hidden />}
          label="Open Preview"
        />
      </StatusBar>
    </div>
  );
};

export default StatusBarActionDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/status-bar-action
```

## Usage

```tsx
import { StatusBarAction } from "@/components/status-bar-action";
```

```tsx
<StatusBarAction
  accelerator="CmdOrCtrl+Shift+C"
  icon={<ClipIcon aria-hidden />}
  label="Save a clip"
  text="Clip"
/>
```

Use it for a control in a [Status Bar](/docs/primitives/status-bar) that isn't a window's shortcut hint: an icon action, a toggle, a menu. It's its own module, so a status bar of hints alone never loads its Tooltip.

Don't use it outside a status bar, where a control is a [Button](/docs/components/button). Don't give it a `title`: `label` names it, and the tooltip shows the name or the hint.

The tooltip follows what the action shows:

| It shows                | Its tooltip                                        |
| ----------------------- | -------------------------------------------------- |
| An icon alone           | The `label`                                        |
| A word (`text`)         | None: the word says it                             |
| Anything, with a `hint` | The `hint`, which is also the button's description |

### As a menu trigger

Its props spread onto the button, so it can be a menu trigger's `render`. The demo's clip length does this:

```tsx
<DropdownMenu>
  <DropdownMenuTrigger
    render={<StatusBarAction label="Clip length" text="30 s" />}
  />
  <DropdownMenuContent side="top">…</DropdownMenuContent>
</DropdownMenu>
```

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `STATUS_BAR_ACTION_CLASS` | 20 px, 11 px tertiary text that brightens on hover, 14 px icons |
| `aria-pressed:text-foreground` | A toggle that's on |
| `text-muted-foreground` | The shortcut, a step above the word |
| `data-slot="status-bar-action"` | The button, kept when a trigger renders it |
| `data-popup-open` | While its menu or tooltip is open, from Base UI |

## Keyboard

| Key              | Action                                    |
| ---------------- | ----------------------------------------- |
| `Tab`            | Moves to the action and shows its tooltip |
| `Enter`, `Space` | Runs it, toggles it, or opens its menu    |

## Accessibility

`label` is the button's `aria-label`, so an icon alone is still named; pass icons with `aria-hidden`. A `hint` becomes the button's `aria-description` as well as its tooltip. `pressed` sets `aria-pressed` for a toggle.

## API reference

Every `button` attribute except `children` and `title`, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | — | The action's name, for assistive tech and the tooltip of an icon alone. |
| `icon` | `ReactNode` | — | A 14 px icon. |
| `text` | `ReactNode` | — | The visible word, when there's room for one. |
| `hint` | `string` | — | More than the name: the tooltip and the button's description. |
| `accelerator` | `string` | — | Its shortcut, as an Electron accelerator. |
| `platform` | `string` | — | darwin, win32, linux… Defaults to data-platform on <html>, then the user agent. |
| `pressed` | `boolean` | — | A toggle that's on. |

# Status Bar (/docs/primitives/status-bar)

```tsx title="components/examples/status-bar-demo.tsx"
"use client";

import { useState } from "react";

import { StatusBar, StatusBarHint } from "@/components/status-bar";

const WINDOWS = [
  { accelerator: "CmdOrCtrl+P", label: "Preview" },
  { accelerator: "CmdOrCtrl+Shift+N", label: "Notes" },
  { accelerator: "CmdOrCtrl+Shift+J", label: "Stream Manager" },
] as const;

const StatusBarDemo = () => {
  const [open, setOpen] = useState<Record<string, boolean>>({
    "Stream Manager": true,
  });
  const [searches, setSearches] = useState(0);
  const toggle = (label: string) =>
    setOpen((current) => ({ ...current, [label]: !current[label] }));
  return (
    <div className="bg-glass-content rounded-panel flex h-44 w-full max-w-xl flex-col overflow-hidden border">
      <div className="p-gutter flex min-h-0 flex-1 flex-col gap-2">
        <div className="bg-video-ground text-video-ground-muted rounded-row grid flex-1 place-items-center text-xs">
          Studio preview
        </div>
        <p aria-live="polite" className="text-meta text-muted-foreground">
          {searches > 0
            ? `Search opened ${searches === 1 ? "once" : `${searches} times`}.`
            : "Click a hint: each one is its shortcut."}
        </p>
      </div>
      <StatusBar
        leading={
          // The session's own words and its clock. In Videorc it's a button
          // that opens Health.
          <span className="text-foreground flex items-center gap-1.5">
            <span
              aria-hidden
              className="glass-dot tone-live size-1.5 rounded-full"
            />
            On air
            <span aria-hidden className="tabular-nums">
              12:04
            </span>
          </span>
        }
      >
        <StatusBarHint
          accelerator="CmdOrCtrl+K"
          label="Search"
          onClick={() => setSearches((count) => count + 1)}
        />
        {WINDOWS.map(({ accelerator, label }) => (
          <StatusBarHint
            accelerator={accelerator}
            key={label}
            label={label}
            onClick={() => toggle(label)}
            pressed={Boolean(open[label])}
          />
        ))}
      </StatusBar>
    </div>
  );
};

export default StatusBarDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/status-bar
```

## Usage

```tsx
import { StatusBar, StatusBarHint } from "@/components/status-bar";
```

```tsx
<StatusBar leading={sessionState}>
  <StatusBarHint
    accelerator="CmdOrCtrl+K"
    label="Search"
    onClick={openSearch}
  />
  <StatusBarHint
    accelerator="CmdOrCtrl+P"
    label="Preview"
    onClick={togglePreview}
    pressed={previewOpen}
  />
</StatusBar>
```

Use it for the window's global state and hints. On the left, the session state in the session's own words ("Ready", "Recording", "On air 12:04"), as the door to Health. On the right, the window shortcuts: Search, Preview, Notes, Stream Manager. Every clickable thing in a status bar is a StatusBarHint or a [Status Bar Action](/docs/primitives/status-bar-action).

Don't repeat these hints on every surface: global hints live here, once. Don't type a shortcut by hand either: a hint takes an Electron accelerator and prints it per platform through [Shortcut Keys](/docs/components/shortcut-keys).

In a narrow window, `labelClassName` hides a hint's word and keeps its key: `labelClassName="hidden md:inline"`.

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `h-status-bar` | The 26 px bar |
| `border-t`, `border-border` | The hairline above it |
| `text-label font-normal` | 11 px at the body's weight |
| `text-muted-foreground` | The bar's own text, and a hint's key |
| `text-subtle` | A hint's word, brightening to `text-foreground` on hover and while pressed |
| `STATUS_BAR_ACTION_CLASS` | The 20 px look every hint and action shares |
| `data-slot` | `status-bar`, `status-bar-leading`, `status-bar-trailing`, `status-bar-hint` |

## Keyboard

| Key              | Action                             |
| ---------------- | ---------------------------------- |
| `Tab`            | Moves through the hints            |
| `Enter`, `Space` | Runs a hint, as its shortcut would |

The shortcuts themselves are the app's to bind.

## Accessibility

The bar is a `<footer>`. A hint is a button named by its key and its word ("⌘K Search"), and `pressed` sets `aria-pressed`. Put the session state in a polite live region (`role="status"`) so a change is announced, and hide its ticking clock from it with `aria-hidden`, or every second would be read out.

## API reference

### StatusBar

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `leading` | `ReactNode` | — | The state, on the left. |
| `children` | `ReactNode` | — | Hints and actions, on the right. |
| `className` | `string` | — | — |

### StatusBarHint

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `accelerator` | `string` | — | The shortcut as an Electron accelerator: CmdOrCtrl+K. |
| `label` | `string` | — | The action's word. |
| `onClick` | `() => void` | — | What the shortcut does. |
| `pressed` | `boolean` | — | The window it opens is open; a click closes it. |
| `platform` | `string` | — | darwin, win32, linux… Defaults to data-platform on <html>, then the user agent. |
| `labelClassName` | `string` | — | Classes for the word alone, to hide it in a narrow window. |
| `className` | `string` | — | — |

# Status Dot (/docs/primitives/status-dot)

```tsx title="components/examples/status-dot-demo.tsx"
"use client";

import { StatusDot } from "@/components/status-dot";

const StatusDotDemo = () => (
  <div className="flex flex-wrap items-center gap-4">
    <StatusDot label="Recording" pulse tone="live" />
    <StatusDot label="Ready" tone="good" />
    <StatusDot label="Reconnecting" pulse tone="warn" />
    <StatusDot label="Encoder stopped" tone="error" />
    <StatusDot label="Idle" />
  </div>
);

export default StatusDotDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/status-dot
```

It brings [Status word](/docs/hooks/status-word) with it.

## Usage

```tsx
import { StatusDot } from "@/components/status-dot";
```

```tsx
<StatusDot label="Recording" pulse tone="live" />
```

It takes the same tones as [Status Badge](/docs/primitives/status-badge): `live` is recording and on air, `error` a failure. The label is a word in sentence case, already mapped from its state; a raw value throws under test.

Use it for ambient state in a header, a status bar or a row's meta. Use a Status Badge when the state needs a chip of its own.

## Examples

### In a header

The dot sits beside a window's or a pane's title and says what it's doing, without competing with the title.

```tsx title="components/examples/status-dot-header.tsx"
"use client";

import { StatusDot } from "@/components/status-dot";

// Ambient status in a header or a status bar: the dot carries the tone, the
// word stays quiet beside the title.
const StatusDotHeader = () => (
  <div className="rounded-row h-toolbar flex w-full max-w-sm items-center justify-between gap-3 border px-3">
    <span className="text-section">Captions reader</span>
    <StatusDot label="Listening" pulse tone="good" />
  </div>
);

export default StatusDotHeader;
```

## Theming

| Token or attribute         | Meaning                                      |
| -------------------------- | -------------------------------------------- |
| `glass-dot`                | The 6 px dot with its halo and glow          |
| `motion-safe:animate-ping` | The pulse; reduced motion stills it          |
| `tone-*`                   | The tone, through `--chip-tone`              |
| `data-tone`                | `good`, `warn`, `error`, `live` or `neutral` |

## Accessibility

Only the label is read; the dot is decoration. A dot with no label says nothing to a screen reader, so give the state a word somewhere nearby.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `"good" \| "warn" \| "error" \| "live" \| "neutral"` | `"neutral"` | — |
| `label` | `string` | — | A word in sentence case. |
| `pulse` | `boolean` | `false` | Rings out from the dot while something runs. |
| `className` | `string` | — | — |

# Theme Toggle (/docs/primitives/theme-toggle)

```tsx title="components/examples/theme-toggle-demo.tsx"
"use client";

import { ThemeToggle } from "@/components/theme-toggle";

const ThemeToggleDemo = () => <ThemeToggle />;

export default ThemeToggleDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/theme-toggle
```

## Usage

```tsx
import { ThemeToggle } from "@/components/theme-toggle";
```

```tsx
<ThemeToggle />
```

It needs next-themes' `ThemeProvider` with `attribute="class"` above it. The click and the D key both come from [useThemeToggle](/docs/hooks/use-theme-toggle), which ignores D in a field and while a dialog or a menu is open. A flip that lands on the computer's own look sets the theme back to System.

Use it for a window's one theme switch. For a control of your own, call `useThemeToggle()` and use its `toggleTheme`.

Don't build a light and dark pair of buttons, or show the shortcut as text beside it: the tooltip shows the key.

## Theming

| Token or attribute              | Meaning                   |
| ------------------------------- | ------------------------- |
| `Button` `ghost`, `size="icon"` | The 28 px icon button     |
| `LightModeIcon`, `DarkModeIcon` | The current theme, filled |

## Keyboard

| Key | Action |
| --- | --- |
| `D` | Switches the theme, outside fields and never from under a dialog or a menu |
| `Enter`, `Space` | On the button, switches the theme |

## Accessibility

The button is named "Toggle color theme" whatever the theme, so scripts and tests can find it. Its [Shortcut Tooltip](/docs/components/shortcut-tooltip) says what a click does, "Switch to light theme" or "Switch to dark theme", with the D key. The theme isn't known on the server, so the icon waits for the client instead of flashing the wrong one as the page hydrates.

## API reference

ThemeToggle takes no props.

# Window Frame (/docs/primitives/window-frame)

```tsx title="components/examples/window-frame-demo.tsx"
"use client";

import { useState } from "react";

import { PinWindowButton } from "@/components/pin-window-button";
import { StatusBar } from "@/components/status-bar";
import { StatusDot } from "@/components/status-dot";
import { WindowFrame, WindowHeader } from "@/components/window-frame";

const NOTES = [
  "Open with the two-camera podcast scene.",
  "Show the Shure MV7 gain staging, then the noise cleanup.",
  "Mention Thursday's livestream at 8 PM.",
] as const;

// Stand-ins for the macOS traffic lights, which the OS draws in a real window.
const TrafficLights = () => (
  <div aria-hidden className="absolute top-3.5 left-5 flex gap-2">
    <span className="bg-foreground/20 size-3 rounded-full" />
    <span className="bg-foreground/20 size-3 rounded-full" />
    <span className="bg-foreground/20 size-3 rounded-full" />
  </div>
);

const WindowFrameDemo = () => {
  const [pinned, setPinned] = useState(true);
  return (
    <WindowFrame className="rounded-panel relative flex h-72 w-full max-w-xl flex-col overflow-hidden border">
      <TrafficLights />
      <WindowHeader platform="darwin" title="Notes">
        <PinWindowButton onPinnedChange={setPinned} pinned={pinned} />
      </WindowHeader>
      <ol
        aria-label="Notes for this recording"
        className="px-gutter flex min-h-0 flex-1 list-decimal flex-col gap-2 overflow-y-auto py-3 pl-9 text-sm select-text"
      >
        {NOTES.map((note) => (
          <li key={note}>{note}</li>
        ))}
      </ol>
      <StatusBar leading={<StatusDot label="Saved" tone="good" />}>
        <span className="text-subtle pr-1.5">3 notes</span>
      </StatusBar>
    </WindowFrame>
  );
};

export default WindowFrameDemo;
```

## Installation

```npm
npx shadcn@latest add @videorc/window-frame
```

## Usage

```tsx
import { WindowFrame, WindowHeader } from "@/components/window-frame";
```

```tsx
<WindowFrame className="flex flex-col">
  <WindowHeader platform={platform} title="Notes">
    <PinWindowButton onPinnedChange={setPinned} pinned={pinned} />
  </WindowHeader>
  …
</WindowFrame>
```

Use it for a single-pane window: Stream Manager, Notes, the Captions reader. Lead with one WindowHeader: the title as the window's `h1`, an optional quiet `meta` fact after it, and the window's few controls at the end. Stream Manager keeps its row to the title: the [Stream Manager](/docs/blocks/stream-manager) block is that window, whole.

Don't use it in the main window, where each page is a [Pane](/docs/primitives/pane) with its Toolbar. Don't stack a third coat inside it either: the frame is the window's one content coat.

## Examples

### A fact and controls, off macOS

`meta` is a quiet fact after the title, such as the Captions reader's state. The children are the window's controls, at the end of the row and out of the drag band. Off macOS the native frame owns the title bar, so the row pads like any other.

```tsx title="components/examples/window-frame-header.tsx"
"use client";

import { useState } from "react";

import { PinWindowButton } from "@/components/pin-window-button";
import { Badge } from "@/components/ui/badge";
import { WindowFrame, WindowHeader } from "@/components/window-frame";

const LINES = [
  "Welcome back, everyone.",
  "Today we're building a scene for a two-camera podcast.",
  "First, add both cameras in Sources.",
] as const;

const WindowFrameHeader = () => {
  const [pinned, setPinned] = useState(true);
  return (
    <WindowFrame className="rounded-panel flex h-56 w-full max-w-md flex-col overflow-hidden border">
      <WindowHeader
        meta={<Badge variant="success">Listening</Badge>}
        platform="win32"
        title="Captions"
      >
        <PinWindowButton onPinnedChange={setPinned} pinned={pinned} />
      </WindowHeader>
      <div className="px-gutter flex min-h-0 flex-1 flex-col gap-1 overflow-y-auto py-3 text-sm select-text">
        {LINES.map((line) => (
          <p key={line}>{line}</p>
        ))}
      </div>
    </WindowFrame>
  );
};

export default WindowFrameHeader;
```

## The traffic lights

Give the window `titleBarStyle: "hiddenInset"`, with the traffic lights centred in the 40 px header row. On macOS the header pads 88 px (`TRAFFIC_LIGHT_GUTTER_CLASS`): the three lights end 74 px in, which leaves the title 14 px of air. It keeps the gutter in fullscreen too. macOS draws the lights over the header when the title bar reveals on hover, and dropping the gutter there would put them on the title.

Pass the platform you know, such as Electron's `process.platform`. Without one, the header reads `data-platform` on `<html>`, then the user agent. A server can't know the reader's platform, so server-rendered markup has no gutter and the client adds it as it hydrates.

## Theming

| Token or attribute | Meaning |
| --- | --- |
| `bg-glass-content` | The content coat over the window coat |
| `h-toolbar` | The 40 px header |
| `pl-[88px]`, `pl-3` | The traffic-light gutter on macOS, a plain row elsewhere |
| `[-webkit-app-region:drag]` | The header moves the window; its controls opt out with `no-drag` |
| `WINDOW_TITLE_CLASS` | The title recipe, 14 px / 600, shared with the Toolbar |
| `data-slot` | `window-frame`, `window-header`, `window-header-title`, `window-header-meta`, `window-header-actions` |

## Accessibility

The title is the window's `h1`. `meta` is plain text after it: if it changes while the window is open (Listening, Paused), put it in a polite live region. Each control in the header needs a name; [Pin Window Button](/docs/primitives/pin-window-button) brings its own.

## API reference

### WindowHeader

Every `header` attribute, plus:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `ReactNode` | — | The window's title, as its h1. |
| `meta` | `ReactNode` | — | A quiet fact after the title. |
| `children` | `ReactNode` | — | The window's controls, at the end and out of the drag band. |
| `platform` | `string` | — | darwin, win32, linux… Defaults to data-platform on <html>, then the user agent. |

### WindowFrame

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | The header and the window's body. |
| `className` | `string` | — | h-screen by default; add the body's layout. |

### useTrafficLightGutter

`useTrafficLightGutter(platform?)` returns `"pl-[88px]"` on macOS and `"pl-3"` elsewhere, for a header row of your own.