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
| Guidance | Practice |
|---|---|
| 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 | Description |
|---|---|---|
value | string | The active state. Selects the step whose ids include it. |
direction | FlowDirection | 1 forward or -1 back, for the step transition.Default: 1 |
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 | 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
<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>