Skip to main content Home About the Design SystemRoadmap OverviewDesignersDevelopers OverviewColorGridIconographyInteractionsSpacingTypography Overview Global colorBox shadowTypographyBorderOpacitySpaceLengthIconBreakpointsMedia queries All elements Accordion Alert Announcement Audio player Avatar Back to top Badge Blockquote Breadcrumb Button Card Chip Code block Call to action Dialog Disclosure Footer Health index Icon Jump links Menu dropdown Navigation link Navigation (primary) Navigation (secondary) Navigation (vertical) Pagination PopoverPlanned Progress stepper Scheme toggle Site status Skeleton Skip link Spinner Statistic Subnavigation Surface Switch Table Tabs Tag Tile Timestamp Tooltip Video embed OverviewColor PalettesCustomizingDevelopers All PatternsAccordionCall to ActionCardFilterFormLink with iconLogo wallSearch barSticky bannerSticky cardTabsTagTile All Personalization PatternsAnnouncement FundamentalsAccessibility toolsAssistive technologiesCI/CDContentContributorsDesignDevelopmentManual testingResourcesScreen readers Design/code status Release notes Get support

Progress stepper

OverviewStyleGuidelinesCodeAccessibilityDemos
OverviewUsage guidelinesAccessibilityResponsive behaviorUsage guidelinesStatusWhen to useStatus checklistOverviewUsage guidelinesAccessibilityResponsive behaviorUsage guidelinesStatusWhen to useStatus checklist

Overview

A progress stepper conveys the steps necessary to complete a process or task, and the status of each step. Steps have titles and descriptions; and each step can be in one of a number of possible states:

  • inactive (yet to be performed)
  • active (currently being performed)
  • warn (succeeded, but with warnings)
  • fail (failed to occur) Or a custom state, set using the icon attribute.

Usage guidelines

  • Use 3-5 steps maximum to reduce cognitive load
  • Designed to complement standard previous/next navigation. Avoid using as the only navigation.
  • When process is completed, users cannot go back and must start over

Accessibility

  • Communicates list structure and step states to screen readers
  • Supports keyboard navigation for linked step titles
  • Maintains logical focus order (left to right, top to bottom)
  • Provides aria-current for the active step
import '@rhds/elements/rh-progress-stepper/rh-progress-stepper.js';
 
<rh-progress-stepper>
  <rh-progress-step state="complete" description="This step has been completed successfully">
    Complete Step
  </rh-progress-step>
  <rh-progress-step state="warn" description="This step has a warning that needs attention">
    Warning Step
  </rh-progress-step>
  <rh-progress-step state="fail" description="This step has failed and needs to be retried">
    Failed Step
  </rh-progress-step>
  <rh-progress-step state="active" description="Currently working on this step">
    Active Step
  </rh-progress-step>
  <rh-progress-step description="This step is not yet started">
    Inactive Step
  </rh-progress-step>
</rh-progress-stepper>

Makes the element vertical at various container query based breakpoints. Breakpoints available 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'

Use when horizontal space becomes limited. The element automatically changes to vertical orientation at screen sizes of <768px.

Sets the orientation of the progress stepper.

  • horizontal - Steps are displayed in a horizontal row (default)
  • vertical - Steps are displayed in a vertical column

Responsive behavior

  • 992px: Padding between steps is set to --rh-space-5xl

  • ≤992px: Padding reduces to --rh-space-2xl
  • <768px: Orientation automatically changes to vertical

Use vertical orientation when horizontal space is limited or when you need to display more detailed step information.

Makes element display as compact.

Usage guidelines

  • Use when there is limited space and less visual prominence is needed
  • Maintain the compact size as designed - do not stretch spacing between steps
  • Switch to default size or different orientation instead of stretching compact
  • Always include step titles even in compact mode for accessibility

Status

When to use

  • Keep users informed about how much time or effort a task will take to complete
  • Track progress in a step-by-step linear process on a single page
  • Display the total number of steps at all times

Status checklist

Edit this page on GitHub
© 2025 Red Hat Deploys by Netlify