# Camera key

> The camera button of a call, built as a lens: seven aperture blades spiral open to show you and shut over you, so nobody wonders if their camera is on.

The camera button in a call is usually a crossed-out icon, and people still ask "can you see me?". This one is the lens itself. When the camera is off, seven aperture blades are shut inside a glass lens in a soft key. Press it and, while your onToggle asks for the camera, the blades open a crack and hunt back and forth beside an amber light. When the stream starts they spiral open, each on its own spring so they ripple round the ring, and you appear in the lens over-bright and soft; the picture then finds its exposure and focus, overshooting once like a real lens, and the light turns green. Press again and the blades spiral shut over you, the picture darkening as they cut the light, and meet with a small knock the key feels. If the camera is blocked, the blades get a little way open, jam and rattle, the key shakes, the light blinks red, and the reason takes the label. Every blade keeps its speed when it is turned round, so you can click as fast as you like and it never jumps; the glass catches the light where your pointer is.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/camera-key.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: none
- Hairline UI components it needs (the CLI installs them too): none
- Docs and live preview: https://hairlineui.com/ui/camera-key
- Registry item (source): https://hairlineui.com/r/camera-key.json

## Usage

```tsx
import { CameraKey } from "@/components/camera-key";

<CameraKey
  stream={stream}
  onToggle={(on) => (on ? startCamera() : stopCamera())}
/>
```

## With getUserMedia

Start the camera when it is turned on and stop its tracks when it is turned off. If the browser refuses, the Error's message is shown on the key.

```tsx
"use client";
import { useRef, useState } from "react";
import { CameraKey } from "@/components/camera-key";

export function CallCamera() {
  const [stream, setStream] = useState<MediaStream | null>(null);
  const current = useRef<MediaStream | null>(null);

  return (
    <CameraKey
      stream={stream}
      onToggle={async (on) => {
        if (!on) {
          current.current?.getTracks().forEach((track) => track.stop());
          current.current = null;
          setStream(null);
          return;
        }
        try {
          const next = await navigator.mediaDevices.getUserMedia({ video: true });
          current.current = next;
          setStream(next);
        } catch (error) {
          const blocked = error instanceof DOMException && error.name === "NotAllowedError";
          throw new Error(blocked ? "Allow the camera in your browser" : "No camera found");
        }
      }}
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `stream` | `MediaStream \| null` | – | Your camera's stream, shown in the lens while it is on. |
| `onToggle` | `(on: boolean) => unknown \| Promise<unknown>` | – | Start or stop your camera. Resolve when it is running; throw an Error to show why it can't start. |
| `on / defaultOn` | `boolean` | `false` | Controlled or starting state. |
| `onOnChange` | `(on: boolean) => void` | – | Every change between on and off. |
| `poster` | `string` | – | A picture for the lens when there is no stream, such as a placeholder. |
| `mirror` | `boolean` | `true` | Show the picture mirrored, as people expect to see themselves. |
| `size` | `number` | `64` | The key's size in px; the lens, blades and light are drawn to scale. |
| `showLabel / labels` | `boolean / { off?, starting?, on?, blocked? }` | `true` | The state under the key, by default "Camera off", "Starting camera", "Camera on" and "Camera blocked". |
| `disabled` | `boolean` | `false` | Dimmed and unpressable. |
| `sound` | `boolean` | `false` | A soft sweep as it opens, a tick as the blades meet, two low notes when it is blocked (synthesised, no files). |
| `onStatusChange` | `(status: "off" \| "starting" \| "on" \| "blocked") => void` | – | Every change of state. |

## States

- **off**: Seven dark aperture blades shut inside a glass lens; the light beside it is dark. Hovering parts them a hair (5%), the way a press would take them.
- **pressed**: The key sinks a touch (4%) and its shadow tightens; the blades lean further the way the press will take them.
- **starting**: While onToggle runs, the blades open to about a fifth and work between 12% and 21% every 0.42s; the light breathes amber.
- **on**: The blades spiral open, each on its own spring, so they ripple round the ring (about 0.5s). Your picture comes in over-bright and blurred, then settles into focus, overshooting once. The light turns green. Hovering closes them a hair (6%).
- **off again**: The blades spiral shut from wherever they are, the picture darkening as they cut the light, and meet with a small knock the key feels. The light goes out.
- **blocked**: The blades open to about 30%, rattle and shake the key, then fall shut after 0.6s; the light blinks red twice and the Error's message replaces the label.
- **pointer**: The glint on the glass follows the pointer and the coating's colour slides the other way; the picture shifts a little behind the glass and the key leans a pixel toward you.
- **reduced motion**: No glint parallax, ripple, hunt, focus or rattle: the blades are simply open or shut, and the light and the label change in place.

## What it handles

A crossed-out camera icon is easy to misread and says nothing while the browser is still asking for permission, so people unmute to ask "can you see me?" or find out too late that they were on camera.

- **On is visible**: Open blades and your own picture mean on; shut blades mean off. A green light beside the lens says it again.
- **The wait is shown**: While the browser asks for the camera, the blades hunt in a crack of an opening and the light breathes amber.
- **Blocked says why**: If onToggle throws, the blades jam and fall shut, the light blinks red, and the Error's message is the label.
- **Your stream, your camera**: Pass the MediaStream you already have; the key shows it mirrored in the lens and never asks for the camera itself.
- **Interruptible**: Seven springs, one per blade, keep their speed when turned round; turning it off while it starts cancels the start.
- **Keyboard and screen readers**: A switch called Camera; Space or Enter toggles it, and on, off, starting and blocked are announced.

## Replaces

camera toggle button, video on off button, camera preview, camera permission state, call controls camera button

## Where it fits

- **Video calls**: The camera button of a meeting, beside mute, in the call's control bar.
- **Pre-join screens**: Check how you look before joining: the lens is the preview.
- **Recording tools**: Turn the face-cam of a screen recorder or a video message on and off.
- **AI with vision**: Let an assistant see through the camera, with an unmistakable sign when it can.

## Notes

- A button with role="switch" named Camera; aria-checked follows the camera and aria-busy is set while it starts. Changes are announced from a status region outside it.
- The iris is drawn from seven springs, one per blade, as SVG paths whose corners are worked out from where each blade's edge crosses its neighbour's, so the blades always meet exactly. One frame loop paints everything and sleeps when the springs rest.
- Turning it off while it is starting cancels the start: whatever onToggle(true) resolves with later is ignored, and onToggle(false) is called.
- The key never asks for the camera; your onToggle does, so it works with any call SDK (LiveKit, Daily, Agora, plain getUserMedia).
- The lens is dark glass in both themes, as a lens is; the key around it takes the page's background and border.

License: MIT (https://hairlineui.com/license#components)
