Stepper/Progress Component

Design a stepper/progress component that shows progress through a multi-step process.

R - Requirements

Key Questions:

• How many steps? (3, 5, 10+)
• Can skip steps? (yes/no, linear vs non-linear)
• Show step labels? (yes/no)
• Show step descriptions? (yes/no)
• Validation? (can't proceed if step invalid)
• Persist progress? (localStorage, URL)

Common Answers:

• 3-10 steps typically
• Linear flow (can't skip)
• Show labels and descriptions
• Step validation required
• Persist in URL (deep linking)

A - Architecture

Stepper Flow:

Stepper Architecture:

Architecture Decisions:

• State machine (step transitions, validation) - Prevents invalid state transitions
• Progress calculation (current step / total steps) - Visual progress indicator
• Validation system (per-step validation) - Block Next if step invalid
• URL synchronization (step in URL hash) - Deep linking, browser back/forward

Relevant Content:

• State Machines - Step flow
• Accessible Forms - Multi-step forms

D - Data Model

State Management:

• Current step (1-indexed)
• Steps array (id, label, description, completed, valid)
• Progress percentage (current / total * 100)
• Validation state (per step)

Persistence:

• URL hash (step in URL, deep linking)
• localStorage (optional, save form data)

I - Interface

Features:

• Step indicators (circles, numbers, icons)
• Step labels (optional)
• Step descriptions (optional)
• Progress bar (optional, percentage)
• Connector lines (between steps)
• Navigation buttons (Previous, Next, Submit)
• Step content (form fields per step)

Accessibility:

• ARIA stepper pattern
• role="group" on container
• aria-label on each step
• aria-current="step" on current step
• aria-disabled on disabled steps
• Keyboard navigation (arrows, Tab)

Relevant Content:

• Keyboard Shortcuts - Step navigation
• Focus Management - Step focus

O - Optimizations

Performance:

• Lazy render steps (only render current step)
• Memoize validation (prevent re-validation)
• Smooth animations (step transitions)

UX:

• Smooth transitions (fade, slide between steps)
• Progress indication (visual progress bar)
• Validation feedback (show errors, prevent next)

Relevant Content:

• Animation Performance - Smooth transitions
• State Machines - Step flow

Implementation Checklist

• Step indicators (circles, numbers, icons)
• Step labels and descriptions
• Progress bar (percentage)
• Connector lines (between steps)
• Current step highlighting
• Completed step indication
• Step validation (prevent next if invalid)
• Navigation buttons (Previous, Next, Submit)
• URL sync (step in URL hash)
• Keyboard navigation (arrows, Tab)
• ARIA attributes (role, aria-current, aria-label)
• Smooth transitions (fade, slide)

Common Pitfalls

❌ Rendering all steps → Performance issues
✅ Lazy render, only render current step

❌ No validation → Users can skip invalid steps
✅ Validate on Next, show errors, prevent progression

❌ No URL sync → Can't share links, lose progress on refresh
✅ Sync step with URL hash, restore on page load

❌ Poor keyboard navigation → Not accessible
✅ Arrow keys to navigate steps, Tab to navigate fields