Step by Step Navigation

Use step by step navigation to break down complex processes into manageable steps that users can follow in sequence.

When to use this pattern

Use step by step navigation when:

• A task has multiple stages that must be completed in order
• Users need to prepare before starting a service
• A process spans multiple visits or days
• The journey involves content or services from multiple sources
• Users need to understand the full journey before they start

When not to use this pattern

• Within a transactional service (use a progress indicator instead)
• When tasks have no specific order
• For simple tasks with fewer than 3 steps

Interactive step by step

The main variant includes collapsible sections and a "Show all/Hide all" toggle. Each step can contain content, task lists, and cost information.

import StepByStep from '@/components/StepByStep';

const steps = [
  {
    id: 'check-eligibility',
    title: 'Check if you can apply online',
    status: 'complete',
    content: <p>You can apply online if you are a citizen...</p>,
    tasks: [
      { label: 'Check eligibility requirements', href: '#' },
    ],
  },
  {
    id: 'get-photo',
    title: 'Get a digital photo',
    status: 'active',
    tasks: [
      { label: 'Photo requirements', href: '#' },
      { label: 'Use the online photo checker', href: '#' },
    ],
  },
  {
    id: 'apply-pay',
    title: 'Apply and pay online',
    logic: 'and', // Shows "You need to:" label
    tasks: [
      { label: 'Start your application', href: '#' },
      { label: 'Pay the passport fee', href: '#', cost: '$180' },
    ],
  },
  {
    id: 'get-passport',
    title: 'Get your new passport',
    content: <p>Your passport will be delivered...</p>,
    tasks: [
      { label: 'Track your application', href: '#' },
    ],
  },
];

<StepByStep
  title="Apply for a passport: step by step"
  introduction="Get a Kaharagian passport for the first time..."
  steps={steps}
/>

Using "and" / "or" logic

When a step contains multiple tasks, you can indicate whether users need to complete all of them (logic: 'and') or choose one (logic: 'or').

const steps = [
  {
    id: 'register',
    title: 'Register your business',
    logic: 'or', // Shows "Choose one of:" label
    tasks: [
      { label: 'Register as a sole trader', href: '#', cost: 'free' },
      { label: 'Register a limited company', href: '#', cost: '$50' },
      { label: 'Register a partnership', href: '#', cost: '$50' },
    ],
  },
  // ...
];

Non-collapsible variant

For shorter step lists or when you want all content visible at once, set collapsible={false}.

<StepByStep
  steps={steps}
  collapsible={false}
  showAllButton={false}
/>

Sidebar variant

Use the sidebar variant to show the step by step navigation alongside content pages that are part of the journey. This helps users understand where they are in the process.

import StepByStepSidebar from '@/components/StepByStepSidebar';

<div style={{ display: 'grid', gridTemplateColumns: '1fr 280px', gap: '24px' }}>
  <main>
    <h1>Passport photo requirements</h1>
    {/* Page content */}
  </main>

  <StepByStepSidebar
    title="Apply for a passport: step by step"
    steps={steps}
    currentStepId="get-photo"
  />
</div>

Step indicator for multi-page forms

For forms split across multiple pages, show which step the user is on:

<p class="step-indicator">Step 2 of 4</p>
<h1>Your contact details</h1>

Component props

StepByStep

Step object

Best practices

Do

• Number the steps clearly
• Use action-oriented titles that describe the task
• Keep step titles short and scannable
• Include links to related content and services
• Show the whole journey from the start so users can plan ahead
• Use the sidebar variant on content pages that are part of the journey
• Show costs where applicable

Don't

• Don't use too many steps (aim for 7 or fewer)
• Don't hide important information in later steps
• Don't change the order or number of steps mid-journey
• Don't use for non-sequential content
• Don't put this pattern on confirmation pages

Accessibility

• Uses semantic ordered list (<ol>) structure
• Step numbers are read to screen readers via visually hidden text
• Collapsible sections use aria-expanded to announce state
• Hidden content uses the hidden attribute
• Focus states meet WCAG 2.1 AA requirements
• Interactive elements are keyboard accessible
• Current step in sidebar is marked with aria-current="step"

CSS Classes

/* Main navigation */
.step-by-step-nav
.step-by-step-nav-title
.step-by-step-nav-intro
.step-by-step-controls
.step-by-step-toggle-all

/* Step list */
.step-by-step
.step-by-step-collapsible
.step-by-step-compact

/* Step items */
.step-by-step-item
.step-by-step-item-active
.step-by-step-item-complete
.step-by-step-header
.step-by-step-number
.step-by-step-title
.step-by-step-title-text
.step-by-step-icon
.step-by-step-content

/* Tasks and content */
.step-by-step-tasks
.step-by-step-task
.step-by-step-logic
.step-by-step-cost

/* Sidebar variant */
.step-by-step-sidebar
.step-by-step-sidebar-header
.step-by-step-sidebar-label
.step-by-step-sidebar-title
.step-by-step-sidebar-controls

/* Step indicator */
.step-indicator