# Radio
URL: https://remocn.dev/docs/ui/components/radio

A radio whose checked/unchecked state is a pure function of the timeline

- Install: `npx shadcn@latest add @remocn/radio`
- Vibe: clean
- Natural length: 120f @ 30fps

A state atom whose appearance (checked, unchecked) is a pure function of the `state` prop. Pass a state directly or drive it from the Remotion timeline via `useCurrentState`. The component reads no frame — only the state value you give it.

## Installation

```bash
npx shadcn@latest add @remocn/radio
```

> **Note**
>
> Installing `radio` automatically installs the shared `remocn-ui` core (`lib/remocn-ui/`) via `registryDependencies`. You do not need to install it separately.

## States

`RadioState` is:

```ts
type RadioState =
  | "unchecked"  // empty ring, border = theme.border, no dot
  | "checked"    // ring border = primary, inner dot fills with primary, scales + fades in
```

`checked` sets the ring border to `primary`, fills the inner dot with `primary`, and animates it in via opacity and scale. `unchecked` renders an empty ring with the theme border color and a hidden dot.

## Snap usage

Pass `state` directly — the component snaps instantly to that visual. Useful for static previews or when you drive state from your own logic:

```tsx
import { Radio } from "@/components/remocn/radio";

export const Scene = () => <Radio state="checked" />;
```

To drive state from the timeline, use `useCurrentState`:

```tsx
import { useCurrentState } from "@/lib/remocn-ui";
import { Radio } from "@/components/remocn/radio";

export const Scene = () => {
  const state = useCurrentState(
    [
      { at: 18, state: "checked" },
      { at: 78, state: "unchecked" },
    ],
    "unchecked",
  );

  return <Radio label="Subscribe to updates" state={state} />;
};
```

Each `at` is a **Sequence-local authored frame**. State persists between steps: `checked` at frame 18 keeps the ring checked until `unchecked` fires at frame 78. See [Concepts](/docs/ui/concepts) for the full `useCurrentState` API.

## Smooth transitions

State changes via `state` snap with no cross-fade. For animated transitions, use `useRadioTransition` from the copied `use-radio-transition.ts` file. It reads the frame, interpolates between state presets, and returns a resolved `RadioStyle` — pass it to the `style` prop:

```tsx
import { Radio } from "@/components/remocn/radio";
import { useRadioTransition } from "@/components/remocn/use-radio-transition";

export const Scene = () => {
  const style = useRadioTransition([
    { at: 18, state: "checked", duration: 14 },
    { at: 78, state: "unchecked", duration: 12 },
  ]);
  return <Radio label="Subscribe to updates" style={style} />;
};
```

The `duration` field on each step overrides the file's `DEFAULT_DURATION` for that specific transition. To globally tune timing and easing, edit `use-radio-transition.ts` directly in your project — that file is yours (shadcn "own your code" philosophy).

`style` takes precedence over `state` when both are provided.

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `state` | `"unchecked" \| "checked"` | `"unchecked"` | Current visual state (snap path). State changes snap — no automatic cross-fade. |
| `style` | `RadioStyle` | — | Resolved animated visual (smooth path). Pass an interpolated RadioStyle from useRadioTransition. Takes precedence over state when provided. |
| `label` | `string` | — | Optional text label rendered next to the ring. Omit for a bare radio. |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` | Ring and label size preset. |
| `theme` | `Partial<RemocnTheme>` | — | Per-component theme override. Merges with the active RemocnUIProvider theme and the mode defaults. Must be concrete oklch/hex/rgb values — not CSS custom properties. |
| `primary` | `string` | — | Convenience override for the primary theme token — merged into theme. |
| `mode` | `"light" \| "dark"` | `"light"` | Sets the base palette. Overrides the mode on RemocnUIProvider when both are present. |
| `className` | `string` | — | Optional className passed to the radio element. |

## Use when
- Demonstrating a single-choice selection moment in a form walkthrough.
- Animating a user choosing between two or more mutually exclusive options.
- Pairing with `cursor` to show a click-and-select interaction on the timeline.

## Don't use when
- The control is binary on/off — use `switch` instead (sliding thumb reads more naturally for toggles).
- You need a multi-select where several options can be active — use `checkbox` instead.
- Options switch with a continuous sliding indicator between segments — use `toggle-group` instead.