# Checkpoint (/docs/agent-ui/components/checkpoint)

Use a checkpoint where the agent saved its work, like before it edits a file, so a person can undo everything after it. It's a quiet line in the conversation with **Restore checkpoint** at its end, and nothing is restored until the person agrees in the dialog.

<Example caption="Press Restore checkpoint, then Restore. The dialog waits for the restore, then the checkpoint reads Restored.">
<Basic />

```tsx
"use client";
import { useState } from "react";
import { Checkpoint } from "@/components/ui/checkpoint";

export default function CheckpointExample() {
  const [restored, setRestored] = useState(false);
  return (
    <Checkpoint
      className="w-full max-w-md"
      description="Before editing auth.ts"
      restored={restored}
      onRestore={() => new Promise<void>((resolve) => setTimeout(resolve, 800)).then(() => setRestored(true))}
    />
  );
}
```
</Example>

## Installation [#installation]

```bash tab="React"
npx shadcn@latest add @kind-ui/checkpoint
```

```bash tab="Web Components"
npx shadcn@latest add @kind-ui/checkpoint-web
```

## Composition [#composition]

```text
Checkpoint
├── CheckpointLabel
├── CheckpointDescription
├── CheckpointLine
├── CheckpointRestore
│   └── CheckpointDialog
│       ├── CheckpointError
│       ├── CheckpointCancel
│       └── CheckpointConfirm
└── CheckpointRestored
```

`Checkpoint` renders these parts when you pass no children: a group named by its `label` and described by its `description`, then a line to the end of the row. `CheckpointRestore` holds UI SDK's Alert Dialog: its trigger is an icon button named by a tooltip, and `CheckpointDialog` is its backdrop and content, with the title, the description and the answers. `CheckpointCancel` and `CheckpointConfirm` are native buttons. `CheckpointRestored` takes Restore's place once the checkpoint is restored.

## Usage [#usage]

### Restoring [#restoring]

Pass `onRestore` to show **Restore checkpoint**. Pressing it opens the dialog, which asks "Restore this checkpoint?" and says "Changes after it will be discarded."; set `confirmTitle` and `confirmDescription` to say more about your checkpoint.

```tsx
<Checkpoint
  label="Checkpoint 3"
  description="Before editing auth.ts"
  onRestore={() => restoreFiles("checkpoint-3")}
/>
```

Only the dialog's **Restore** calls `onRestore`, with `details.source` saying how it was pressed. Return a promise to keep the dialog open until it settles: both answers are disabled meanwhile, a second press calls nothing, and Escape waits. When it resolves, the dialog closes and focus returns to **Restore checkpoint**. A rejection keeps the dialog open with "Couldn't restore. Try again." beside the answers, and screen readers hear "Checkpoint not restored".

### Restored [#restored]

Once the host has restored the checkpoint, pass `restored`. "Restored" takes the button's place at the same height, so nothing above or below it moves, and screen readers hear "Checkpoint restored". If the button had focus, focus moves to "Restored". Setting `restored` while the dialog is open closes it.

### Keyboard [#keyboard]

**Restore checkpoint** is one Tab stop; Enter or Space opens the dialog with focus on **Cancel**, the answer that changes nothing. Tab stays inside the dialog, and Escape closes it and returns focus to the button. A press outside never closes it.

### The Dialog's State [#the-dialogs-state]

Pass `open` and `onOpenChange` to control the dialog, or `defaultOpen` to start with it open. `onOpenChange` gets UI SDK's reason, like `trigger-press`, `escape-key`, `close-press` or `action` after a restore.

### Motion [#motion]

The dialog rises and fades in, its backdrop and the tooltip fade, and "Restored" fades in. Under `prefers-reduced-motion`, or with `motion="reduced"`, these only fade, over 120 ms, and with `motion="none"` they change at once.

## API Reference [#api-reference]

### CheckpointOptions

| Prop                  | Type                                                                                          | Description                                                                                                                                                                                                                              |
| --------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label?`              | `string \| undefined`                                                                         | Names the checkpoint, like "Checkpoint 3". Default: `"Checkpoint"`                                                                                                                                                                       |
| `description?`        | `string \| undefined`                                                                         | What the checkpoint was taken before, like "Before editing auth.ts".                                                                                                                                                                     |
| `onRestore?`          | `((details: ActionDetails) => unknown) \| undefined`                                          | Called when a person confirms in the dialog. Shows Restore while set. Return a promise to keep the dialog open until it settles: a rejection keeps it open with an error, and Restore works again. `details.source` says who pressed it. |
| `restored?`           | `boolean \| undefined`                                                                        | Whether the host restored the checkpoint. Shows "Restored" in place of Restore, and closes the dialog. Default: `false`                                                                                                                  |
| `confirmTitle?`       | `string \| undefined`                                                                         | Default: `"Restore this checkpoint?"`                                                                                                                                                                                                    |
| `confirmDescription?` | `string \| undefined`                                                                         | Default: `"Changes after it will be discarded."`                                                                                                                                                                                         |
| `open?`               | `boolean \| undefined`                                                                        | Whether the dialog is open. Passing it controls it: change it in `onOpenChange`.                                                                                                                                                         |
| `defaultOpen?`        | `boolean \| undefined`                                                                        | Whether the dialog is open at first, when `open` isn't passed. Default: `false`                                                                                                                                                          |
| `onOpenChange?`       | `((open: boolean, details: ChangeDetails<AlertDialogOpenChangeReason>) => void) \| undefined` | Called when the dialog opens or closes, with what caused it.                                                                                                                                                                             |
| `agentConfirm?`       | `boolean \| undefined`                                                                        | Whether an agent needs a person to approve `restore` and every action on the checkpoint. Either way, an agent pressing the dialog's Restore needs a person. Default: `true`                                                              |
| `motion?`             | `"auto" \| "none" \| "reduced"`                                                               | How the dialog opens and closes, and how "Restored" fades in. `"auto"` follows `prefers-reduced-motion`. Default: `"auto"`                                                                                                               |

### Agent [#agent]

An agent connected with `createAgent` finds the checkpoint by its label and reads whether its dialog is open. Its `restore` opens the dialog, the same as a press, and is offered while **Restore checkpoint** shows and the dialog is closed. It never calls `onRestore`: only the dialog's **Restore** does, and an agent pressing that always needs a person to confirm, unless the host's `allow` lets it through. While `agentConfirm` is on, `restore` and every other action on the checkpoint need a person too.

### CheckpointAgentActions

| Prop      | Type                        | Description                                                                                                                                                                               |
| --------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `restore` | `(() => void) \| undefined` | Opens the dialog, as pressing Restore does. Offered only while `onRestore` is set, the checkpoint isn't `restored` and the dialog is closed. Only the dialog's Restore calls `onRestore`. |

<Caption>
Runs in React and Web Components. On `<kind-checkpoint>`, props are kebab-case attributes, so `confirmTitle` is `confirm-title`, and `open` is a property too. Restore needs the `can-restore` attribute, and the dialog's Restore fires `restore`: call `event.detail.waitUntil(promise)` to keep the dialog open. The element fills in its parts when it has no children.
</Caption>