# Dialog
URL: https://remocn.dev/docs/ui/components/dialog

A modal dialog whose opened/closed state is a pure function of the timeline

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

A state atom whose appearance (closed, opened) 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. The wrapper is transparent by design: Dialog is a modal layer meant to compose over another scene, so it does not paint an opaque background. Unlike AlertDialog, Dialog is a generic (non-destructive) modal — its primary action uses the theme `primary` color, and it renders a close (X) button in the top-right corner of the popup card.

## Installation

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

> **Note**
>
> Installing `dialog` automatically installs the shared `remocn-ui` core (`lib/remocn-ui/`) via `registryDependencies` (`["remocn-ui"]`). You do not need to install it separately. If you want to pair Dialog with the Button as its trigger in the canonical lifecycle example, install `button` separately.

## States

`DialogState` is:

```ts
type DialogState =
  | "opened"  // backdrop dims to 50% black, popup fades in and zooms from 0.95 → 1
  | "closed"  // panel hidden, backdrop clear (overlay opacity 0, popup opacity 0, scale 0.95)
```

`opened` reveals the backdrop dim (scales up to `MAX_OVERLAY_ALPHA = 0.5`) and fades the popup card in while zooming it from `0.95` to `1` and lifting it 8 px upward. `closed` hides the backdrop and the popup entirely.

## 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 { Dialog } from "@/components/remocn/dialog";

export const Scene = () => <Dialog state="opened" />;
```

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

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

export const Scene = () => {
  const state = useCurrentState(
    [
      { at: 32, state: "opened" },
      { at: 92, state: "closed" },
    ],
    "closed",
  );

  return <Dialog title="Edit profile" state={state} />;
};
```

Each `at` is a **Sequence-local authored frame**. State persists between steps: `opened` at frame 32 keeps the dialog visible until `closed` fires at frame 92. 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 `useDialogTransition` from the copied `use-dialog-transition.ts` file. It reads the frame, interpolates between state presets, and returns a resolved `DialogStyle` — pass it to the `style` prop:

```tsx
import { Dialog } from "@/components/remocn/dialog";
import { useDialogTransition } from "@/components/remocn/use-dialog-transition";

export const Scene = () => {
  const style = useDialogTransition([
    { at: 32, state: "opened", duration: 16 },
    { at: 92, state: "closed", duration: 12 },
  ]);
  return <Dialog title="Edit profile" style={style} />;
};
```

The `duration` field on each step overrides the file's `DEFAULT_DURATION` (= `12`) for that specific transition. To globally tune timing and easing, edit `use-dialog-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` | `"opened" \| "closed"` | `"closed"` | Current visual state (snap path). State changes snap — no automatic cross-fade. |
| `style` | `DialogStyle` | — | Resolved animated visual (smooth path). Pass an interpolated DialogStyle from useDialogTransition. Takes precedence over state when provided. |
| `title` | `string` | `"Edit profile"` | Headline of the dialog popup. |
| `description` | `string` | `"Make changes to your profile here. Click save when you're done."` | Body copy displayed under the title. |
| `actionLabel` | `string` | `"Save changes"` | Label of the confirming (primary) action button. |
| `cancelLabel` | `string` | `"Cancel"` | Label of the dismissing action button. |
| `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. |
| `mode` | `"light" \| "dark"` | `"light"` | Sets the base palette. Overrides the mode on RemocnUIProvider when both are present. |
| `className` | `string` | — | Optional className applied to the popup card element. |

## Use when
- Showing a non-destructive modal (edit form, settings, profile update) opening and closing on the timeline.
- A centered overlay needs a title, description, and primary/cancel actions.
- Composing a trigger-to-modal sequence: `button` state="press" → `dialog` state="open".

## Don't use when
- The action is irreversible or destructive — use `alert-dialog` instead.
- The panel should slide from the bottom edge — use `drawer` instead.
- The overlay is non-modal and contextual — use `dropdown-menu` or `context-menu` instead.