Skip to content
Mosaic
On this page

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

GuidancePractice
DoMark the element a step should focus when it enters with useFlowAutoFocus, exported from this unit.
DoKeep the surface outside the flow and render one Flow.Root per surface. The rules are in the Views guide (mosaic guides inspect views).
Don’tSwap 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

PropTypeDescription
valuestringThe active state. Selects the step whose ids include it.
directionFlowDirection1 forward or -1 back, for the step transition.Default: 1
stateStatePassed to children, so an exiting step keeps the content of its last active render.
children(state: State) => React.ReactNodeRenders 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

PropTypeDescription
idsreadonly 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>