Flow
Headless, unstyled viewport that shows one step of a multi-step flow at a time, keeping the outgoing step mounted, inert and aria-hidden until its exit transition ends. Measures the active step into --cl-flow-step-height on the root. useFlowAutoFocus marks what a step focuses when it enters, and useFlowStepActive is false inside an exiting step.
Use for
- the base for a styled component that swaps screens on one surface
- focusing a field when a step of a multi-step flow enters
- knowing whether content sits in an exiting step
Practices
| Guidance | Practice |
|---|---|
| Don’t | Use the primitive in a feature. Use the styled Flow from src/components/flow instead, as the Views guide says (mosaic guides inspect views). |
| Do | List every controller state a screen covers in one Flow.Step ids, such as its pending and error states, so moving between them does not transition. |
| Do | Attach useFlowAutoFocus() to the field a step should focus when it enters. |
| Do | Style Flow.Root with overflow: clip, not hidden, so focusing a sliding step cannot scroll it. |
| Do | Transition the root height only under data-transitioning, so a resize inside the active step is not animated twice. |
API reference
Flow.Root
Renders a div, or the render element. Carries data-initial through the first measured frame, data-transitioning from a step change until its own height transition ends, and data-height-change of grow or shrink.
| Prop | Type | Description |
|---|---|---|
value | string | The active controller state. The step whose ids include it is shown. |
direction | FlowDirection | 1 forward or -1 back. Each step exposes it as --cl-flow-transition-direction.Default: 1 |
Flow.Step
Renders while active or exiting, with data-open, data-closed, data-starting-style and data-ending-style. An exiting step keeps the children of its last active render. The first active step gets no data-starting-style.
| Prop | Type | Description |
|---|---|---|
ids | readonly string[] | The controller states this step shows for. |
Examples
Two steps
<Flow.Root value={status} direction={direction}>
<Flow.Step ids={['password', 'password-pending']}>
<PasswordView />
</Flow.Step>
<Flow.Step ids={['code', 'code-pending']}>
<CodeView />
</Flow.Step>
</Flow.Root>