Guided Flow

Overview

GuidedFlow is a compound workflow component for step-by-step guided experiences.

It is not just for "creating new stuff." It is better understood as a UI kit for:

• progressive disclosure
• stepwise decision-making
• inline explanatory help
• final preview and review before commit

That makes it a good fit for creation flows, but also for import, setup, assignment, conversion, and other guided workflows.

Compound API

Typical Structure

<div className="relative">
  <div className="absolute right-0 top-0 z-10 flex h-7 items-center">
    <GuidedFlow.ProgressionPips
      steps={steps}
      currentStep={currentStep}
      onStepClick={setCurrentStep}
      canNavigateToStep={(step) => step <= currentStep}
    />
  </div>

  <GuidedFlow.Step stepKey={currentStep} direction={stepDirection}>
    <GuidedFlow.StepQuestion
      title="Who are you adding?"
      description="Start with identity, then reveal the operational choices."
    />

    <GuidedFlow.StepField label="Email" required>
      <Input label="Email" />
    </GuidedFlow.StepField>
  </GuidedFlow.Step>
</div>

This is the same overall structure used in the story and in ImportSingleFranchiseeModal.tsx.

Step Transitions

GuidedFlow.Step is responsible for the animated horizontal transition between steps.

Use:

• stepKey to ensure the content remounts and animates when the active step changes
• direction={1 | -1} when forward and backward motion should feel different

Step Questions

Use GuidedFlow.StepQuestion to frame each step as a decision or focused task.

<GuidedFlow.StepQuestion
  title="What entity are they a part of?"
  description="If the entity doesn't exist yet, create it first."
/>

This is one of the core strengths of the pattern: each step can explain the user's immediate task instead of presenting a long undifferentiated form.

Step Fields

GuidedFlow.StepField is the shared wrapper for:

• label
• helper text
• required marker
• click-triggered tooltip

<GuidedFlow.StepField
  label="Franchisee entity"
  description="Search for the legal or operating entity this person belongs to."
  tooltip="Choose the entity that should receive ownership and invite-related workflow events."
>
  <Select
    selected={field.value}
    onSelect={field.onChange}
    options={options}
    placeholder="Choose a franchisee entity"
    searchable
  />
</GuidedFlow.StepField>

Use it when the extra framing helps the user understand why the field matters. If the child field already handles its own label and error, StepField works best as contextual framing rather than a replacement field shell.

Preview And Review

GuidedFlow.StepPreview* is what makes the pattern feel complete instead of just being a stepped form.

<GuidedFlow.StepPreview className="space-y-5">
  <GuidedFlow.StepPreviewSection title="Franchisee">
    <GuidedFlow.StepPreviewItem label="Name" value="Jamie Rivera" />
    <GuidedFlow.StepPreviewItem label="Email" value="jamie@franchisee.com" />
  </GuidedFlow.StepPreviewSection>
</GuidedFlow.StepPreview>

This is ideal for:

• review-before-submit
• configuration summaries
• showing the consequences of a choice before commit

ProgressionPips

GuidedFlow.ProgressionPips is part of the GuidedFlow story and should usually be documented and used with it.

It supports:

• current step display
• optional step click navigation
• optional canNavigateToStep gating

It is most useful when users may revisit completed steps, but should not jump ahead to unfinished ones.

Brand Dashboard Usage

Representative usage:

Important Conventions

• GuidedFlow provides the workflow structure, not the surrounding shell. It is commonly placed inside a Modal, but that is not required.
• The component does not manage form state, navigation rules, or validation for you. The parent owns those concerns.
• GuidedFlow.StepField is a framing component, not a replacement for field components such as Input, Select, or Toggle.
• ProgressionPips should usually allow navigation only to already completed or currently available steps.
• The preview step is an important part of the pattern; it is usually what turns a stepped form into a guided workflow.

Guidelines

• Do use GuidedFlow for step-by-step workflows with a clear sequence and a meaningful review state
• Do use StepQuestion to keep each step focused and explanatory
• Do use StepPreview for final confirmation or consequence preview
• Don't use GuidedFlow for long flat forms with no real step logic
• Don't force every wizard-like experience into GuidedFlow if the steps are really separate full screens or workspaces