Status
The status of the component
Component checklist
Ready for use!
Repository
A link to the repo where the component lives.
Label and Helper Text
Effective labels and helper text are crucial for user comprehension within each step.
- Conciseness: Step titles and helper text should be concise and easily scannable.
- Line Limit: Limit both helper text and step titles to a maximum of two lines. Content exceeding this limit should be truncated to maintain visual cleanliness and prevent excessive vertical space.
- Casing: Use sentence case for both step titles and helper text. Only the first letter of the first word should be capitalized, with no punctuation at the end.
- Character Limits: While context-dependent, aim for step titles to be succinct (e.g., under 25-30 characters) and helper text to provide brief, supplementary guidance.
Do
Do limit step titles and helper text to a maximum of two lines to prevent visual clutter.
Don't
Don't exceed two lines for step titles or helper text.
Error Handling
Error handling within the Stepper component is integrated with our broader Error Management documentation to provide clear, actionable feedback. The Stepper acts only as an additional high-level indicator of where issues exist.
Step Helper Text for Errors
When an error occurs, avoid putting specific validation details (e.g., "Email address must contain @") in the helper text of the step. The specific error message should always be displayed inline with the form field itself.
The helper text for a step should provide general guidance. In an error state, its content can be updated to a clear, high-level instruction such as, "Review and correct the information" to direct the user's attention without being redundant.
Do
Provide a high-level instruction. The helper text should offer a general direction, such as "Review and correct the information" to guide the user's attention.
Don't
Put specific error details in the helper text. Avoid redundant messages like "Your email address is invalid" within the step's helper text itself.
Step Error State Behavior
Displaying Errors: A step's error state should be triggered and become visually apparent immediately after a failed validation attempt.
Helper Text during Errors: When a step enters an error state, its helper text should be updated to a clear instructional message, such as "Review and correct the information". This provides a concise, high-level instruction that guides the user's focus.
Removing Errors: An error state should be automatically removed as soon as the user corrects the underlying issue. The moment the associated form fields meet all validation criteria, the step's error state and its helper text should both revert to their original, non-error states, providing instant feedback and a sense of progress.
Layout Orientation: Vertical and Horizontal Stepper
The Stepper component adapts to different screen real estates and content requirements through its orientation.
Choose a vertical or horizontal orientation for the stepper based on the use case and UI.
Linear and Non-linear Stepper
The Stepper component can support different user flow types.
Linear Stepper
Requires users to complete steps in a strict, sequential order. Users cannot skip steps. This is appropriate for processes where dependencies dictate a specific progression.
Non-linear Stepper: Allows users to revisit or skip steps, providing more flexibility. This is suitable for workflows where steps are independent or can be completed in any order after initial access.
Stepper Navigation (Clickable Steps and Separate Buttons)
Effective navigation is crucial for user progression and accessibility. The Stepper component supports dual navigation methods.
- Clickable Steps: Each step's title area should be clickable, allowing users to directly navigate to a previous or future step (in non-linear flows).
- Separate Navigation Buttons: Dedicated navigation buttons (e.g., "Next," "Back," "Submit") should always be provided in the footer of the form. These buttons significantly enhance both usability and keyboard navigation, providing clear, persistent controls for advancing or regressing in the workflow.
Do
Always provide separate navigation buttons (e.g., "Next," "Back") in the form footer for optimal usability and keyboard accessibility.
Don't
Don't rely solely on clickable steps for navigation; always include explicit navigation buttons in the form footer.
Alignment and Placement on Page
Consistent alignment contributes to visual clarity and user predictability.
- Navigation Button Alignment: Navigation buttons should always be aligned to the right in the form footer.
- Fixed Positioning (Long Forms): For longer forms that may require scrolling, consider fixed positioning options for both the Stepper component itself and the navigation buttons. This ensures the user's current position and navigation controls are always visible, regardless of scroll depth.
Example of stepper alignment and form footer with the CTA buttons to the right.
Spacing
Consistent spacing ensures readability and visual hierarchy within the Stepper.
Component-Driven Spacing
Spacing between steps and within elements of the Stepper is managed by the component's internal styles to ensure visual balance and adherence to the design system's layout principles. Avoid custom spacing adjustments.
Spacing between Stepper and Content
Maintain clear visual separation between the Stepper component and its associated content area (e.g., a form or details panel) a consistent 40px space (form_control.form_stepper.gap) should be applied between stepper and content. This ensures readability and a clear visual hierarchy without disconnecting the two elements.
Horizontal Stepper
Vertical Stepper
Best Practices
Employing the Stepper effectively enhances complex workflows.
Clear Progress Indication
Always ensure a clear indication of the user's current position and overall progress within the flow.
Logical Steps
Each step should represent a distinct, logical phase of the overall process. Avoid overly granular steps that don't add significant value.
Do
Logical steps, each step should represent a distinct, logical step of the overall process.
Don't
Don’t overly granular steps.
Providing Feedback
Integrate completion and error feedback directly into the Stepper's visual states and associated messaging (as detailed in the Error Handling section).
"Review" Variant/Summary
Consider implementing a distinct "review" variant or a final summary step to confirm completion and provide an overview of the entered information.
Integration
Using a prominent main page header for the overall topic and a clear, secondary heading for the content within each active stepper step creates a strong semantic and visual link. The secondary heading should always match the title of the current stepper, reinforcing the user's context and guiding them clearly through each phase of the process.
Example of header hierarchy:
1. Main page header (semantic/heading/lg/semi_bold)
2. Secondary heading matching to the active step title (semantic/heading/md/semi_bold)
Related Components & Patterns