# Step (/docs/agent-ui/components/step)

Use a step for each thing the agent does, like reading a file or running a command. Its icon shows the status, and its panel holds the details.

<Example caption="Press Read the logs, or focus it and press Enter or Space, to show its details.">
<g />

```tsx
import { Step, StepContent, StepIcon, StepMeta, StepTitle, StepTrigger } from "@/components/ui/step";

export default function StepExample() {
  return (
    <div className="flex flex-col gap-1">
      <Step status="complete">
        <StepTrigger>
          <StepIcon />
          <StepTitle>Read the logs</StepTitle>
          <StepMeta>2s</StepMeta>
        </StepTrigger>
        <StepContent>
          <p>Three requests timed out after 30 seconds.</p>
        </StepContent>
      </Step>
      <Step status="running" defaultOpen>
        <StepTrigger>
          <StepIcon />
          <StepTitle>Add a retry with backoff</StepTitle>
        </StepTrigger>
        <StepContent>
          <p>Editing src/client.ts.</p>
        </StepContent>
      </Step>
    </div>
  );
}
```
</Example>

## Installation [#installation]

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

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

## Composition [#composition]

```text
Step
├── StepTrigger
│   ├── StepIcon
│   ├── StepTitle
│   └── StepMeta
├── StepContent
└── StepChildren
```

The trigger renders a native button that shows or hides the content. Put a duration or a count in `StepMeta`, and nested steps in `StepChildren`, which stays visible while the step is closed.

## Usage [#usage]

### Status [#status]

Set `status` as the work moves along: `pending`, `running`, `awaiting-input`, `complete`, `error` or `cancelled`. A step opens on its own while it's running or waiting for input, and closes when it completes. Once someone opens or closes it, it stays that way. Pass `autoOpen="never"` to leave every step closed until someone opens it.

When a step completes, fails, is cancelled or needs input, it tells screen readers politely. The content stays in the page while it's closed, so the browser's find in page still reaches it.

### A List of Steps [#a-list-of-steps]

Put steps in a `StepList` so the keyboard moves between them with the arrow keys, and Tab leaves the list in one press. Render each trigger through a `StepListItem`:

```tsx
<StepList aria-label="Agent steps">
  <Step status="complete">
    <StepListItem value="logs" render={<StepTrigger />}>
      <StepIcon />
      <StepTitle>Read the logs</StepTitle>
    </StepListItem>
    <StepContent>Three requests timed out.</StepContent>
  </Step>
</StepList>
```

## API Reference [#api-reference]

### StepOptions

| Prop               | Type                                                                                   | Description                                                                                                                                                                                    |
| ------------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status?`          | `"awaiting-input" \| "cancelled" \| "complete" \| "error" \| "pending" \| "running"`   | What the step is doing. The icon shows it. Default: `"pending"`                                                                                                                                |
| `kind?`            | `string \| undefined`                                                                  | Written as `data-kind`, for styling by step type.                                                                                                                                              |
| `label?`           | `string \| undefined`                                                                  | Names the step in announcements. Defaults to the title part's text.                                                                                                                            |
| `open?`            | `boolean \| undefined`                                                                 | Whether the content shows. Passing it controls it: change it in `onOpenChange`.                                                                                                                |
| `defaultOpen?`     | `boolean \| undefined`                                                                 | Whether the content shows at first, when `open` isn't passed. Defaults to open while `status` is `running` or `awaiting-input`, unless `autoOpen` is `"never"`.                                |
| `onOpenChange?`    | `((open: boolean, details: ChangeDetails<StepOpenChangeReason>) => void) \| undefined` | Called when the step opens or closes, with what caused it.                                                                                                                                     |
| `autoOpen?`        | `"never" \| "running"`                                                                 | With `"running"`, the step opens while running or awaiting input and closes on completion, until someone toggles it. With `"never"`, only a person or your code opens it. Default: `"running"` |
| `durationSeconds?` | `number \| undefined`                                                                  | Written as `--kind-step-duration`.                                                                                                                                                             |
| `motion?`          | `"auto" \| "none" \| "reduced"`                                                        | `"auto"` follows `prefers-reduced-motion`. Default: `"auto"`                                                                                                                                   |

### Agent [#agent]

An agent connected with `createAgent` reads each step's `open` and `status`. It can run these actions, and press the trigger like a person would:

### StepAgentActions

| Prop       | Type            | Description                                               |
| ---------- | --------------- | --------------------------------------------------------- |
| `expand`   | `() => boolean` | Opens the step. Returns whether the change was accepted.  |
| `collapse` | `() => boolean` | Closes the step. Returns whether the change was accepted. |

<Caption>
Runs in React and Web Components. On `<kind-step>`, each prop is a kebab-case attribute, so `autoOpen` is `auto-open`, and each callback is a lowercase event, so `onOpenChange` fires `openchange`.
</Caption>