# Flow

One screen replacing another on the same card or dialog. The surface stays put, its height animates, and the outgoing step stays mounted, inert, until its exit finishes. Wraps the headless `Flow` primitive.

## Use for

- one screen replacing another on the same card or dialog
- a multi-step flow on one surface
- animating between a list and a create screen

## Practices

- Do: Mark the element a step should focus when it enters with `useFlowAutoFocus`, exported from this unit.
- Do: Keep the surface outside the flow and render one `Flow.Root` per surface. The rules are in the Views guide (`mosaic guides inspect views`).
- Don't: Swap screens with a conditional or an early return. The new screen pops in instead of animating.

## API reference

### Flow.Root

The viewport. Measures the active step into `--cl-flow-step-height` and carries `data-value`, `data-initial`, `data-transitioning` and `data-height-change`.

Slot: `cl-flow-root`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | The active state. Selects the step whose `ids` include it. |
| `direction` | `FlowDirection` | `1` | `1` forward or `-1` back, for the step transition. |
| `state` | `State` |  | Passed to `children`, so an exiting step keeps the content of its last active render. |
| `children` | `(state: State) => React.ReactNode` |  | Renders the steps from `state`. |

### Flow.Step

One screen. Renders while active or exiting, with `data-open`, `data-closed`, `data-starting-style`, `data-ending-style` and `data-step` (its first id).

Slot: `cl-flow-step`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ids` | `readonly string[]` |  | The states this step renders for. Moving between them does not start a transition. |

## Examples

### A list and a create screen

```tsx
<Flow.Root value={step} direction={step === 'list' ? -1 : 1} state={props}>
  {current => (
    <>
      <Flow.Step ids={['list']}>
        <ListStep {...current} />
      </Flow.Step>
      <Flow.Step ids={['create']}>
        <CreateStep {...current} />
      </Flow.Step>
    </>
  )}
</Flow.Root>
```

## Related

- [Card](/docs/components/card.md)
- [Dialog](/docs/components/dialog.md)
- `useFlowAutoFocus`
