Skip to main content Home
About About the Design SystemRoadmap
Get started OverviewDesignersDevelopers
Foundations OverviewColorGridIconographyInteractionsSpacingTypography
Tokens Overview Global colorBox shadowTypographyBorderOpacitySpaceLengthIconBreakpointsMedia queries
Elements 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 Navigation (primary) Navigation (secondary) Pagination PopoverPlanned Progress stepper Scheme toggle Site status Skeleton Skip link Spinner Statistic Subnavigation Surface Switch Table Tabs Tag Tile Timestamp Tooltip Video embed
Theming OverviewColor PalettesCustomizingDevelopers
Patterns All PatternsAccordionCardFilterFormLink with iconLogo wallSearch barSticky bannerSticky cardTabsTagTile
Personalization All Personalization PatternsAnnouncement
Accessibility FundamentalsAccessibility toolsAssistive technologiesCI/CDContentContributorsDesignDevelopmentManual testingResourcesScreen readers
Design/code status Release notes Get support

Progress stepper

OverviewStyleGuidelinesCodeAccessibilityDemos
ImportingUsagerh-progress-stepperUsage guidelinesAccessibilityResponsive behaviorUsage guidelinesrh-progress-stepImportingUsagerh-progress-stepperUsage guidelinesAccessibilityResponsive behaviorUsage guidelinesrh-progress-step

Importing

Add rh-progress-stepper to your page with this import statement:

<script type="module">
  import '@rhds/elements/rh-progress-stepper/rh-progress-stepper.js';
</script>
Copy to Clipboard Wrap lines

To learn more about installing RHDS elements on your site using an import map read our getting started docs.

Usage 

<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>

<script type="module">
  import '@rhds/elements/rh-progress-stepper/rh-progress-stepper.js';
</script>
Copy to Clipboard Wrap lines

rh-progress-stepper

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
Slots 1
Slot Name Summary Description

Use this slot for <rh-progress-step> items Each step should include title and optional description
Attributes 3
Attribute DOM Property Description Type Default
vertical-at verticalAt

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.

 
'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'
 
undefined
orientation orientation

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.

 
ProgressStepsOrientation
 
'horizontal'
compact compact

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
 
boolean
 
false
Methods 0
None
Events 0
None
CSS Shadow Parts 0
None
CSS Custom Properties 0
None
Design Tokens 15
Token Summary Copy
--rh-color-border-strong

Connecting line color between steps
--rh-color-text-primary

Step label color (default state)
--rh-length-xl

Base icon container size
--rh-size-icon-02

Icon size for step indicators
--rh-color-border-subtle

Connecting line color for inactive steps
--rh-length-2xl

Horizontal padding between steps in compact mode

Vertical padding between steps in compact vertical mode
--rh-length-xs

Vertical spacing between rows in step grid

Vertical spacing between step elements
--rh-length-lg

Horizontal gap between step elements

Vertical spacing between stepper elements

Horizontal gap between icon and label in vertical mode

Horizontal padding in compact horizontal mode

Vertical padding in compact vertical mode

Horizontal padding override for compact steps
--rh-color-status-note

Color for active step in compact mode
--rh-color-status-success

Color for completed step in compact mode
--rh-color-yellow-50

Warning step color in light mode
--rh-color-yellow-30

Warning step color in dark mode
--rh-color-yellow-60

Warning step label color in light mode
--rh-color-yellow-20

Warning step label color in dark mode
--rh-color-status-danger

Color for failed step icon in compact mode

Color for failed step label in compact mode

rh-progress-step

A progress step represents a single step in a progress stepper. Each step can have different states and may include an icon, label, and description. Steps can also be linked to URLs.

Slots 3
Slot Name Summary Description

A short title (1 to 3 words) for each step is required and serves as the step's accessible name. Titles can be hyperlinked. Do not add punctuation to end.
icon

custom icon for the step

Overrides the icon and icon-set attributes. Prefer using the icon attribute and the (default) UI Icon set. Avoid slotting content here if the step is in the warn or fail state, Since those states should always show their prescribed icons.
description

Elaborative, optional description for the step

Rich HTML content can be slotted here , to override the (plain text) description attribute. Avoid slotting links, images, block-level content, etc.: descriptions should be prose only (around 40 characters or a max of 2 lines at the 768px breakpoint).
Attributes 5
Attribute DOM Property Description Type Default
state state

Sets the state of the progress step

  • inactive - The step is not active
  • active - The step is currently active
  • complete - The step has been completed
  • warn - The step is in a warning state
  • fail - The step has failed
  • custom - The step uses a custom icon
 
ProgressStepState
 
unknown
description description

Sets the description text for the progress step when more context is needed. Descriptions are secondary to titles.

It is overridden by the description slot.

 
string
 
unknown
icon icon

Can be used to set a custom icon for the step. When the step is in the warn or fail state, it should not have a custom icon. If there's no custom icon, the default active or inactive icon will appear.

It can be overridden by the icon slot.

 
IconNameFor<IconSetName>
 
unknown
icon-set iconSet

Icon set for the icon property - 'ui' by default

 
IconSetName
 
'ui'
href href

Sets a URL to make the step's title clickable. Only completed or current steps will appear linked. The linked title will use our inline link styling, with gray, dashed underlines.

 
string
 
unknown
Methods 0
None
Events 1
Event Name Description
change

fired when this step becomes active
CSS Shadow Parts 0
None
CSS Custom Properties 0
None
Design Tokens 21
Token Summary Copy
--rh-color-text-primary

Icon color (default state)

Label text color (default state)
--rh-length-5xl

Horizontal padding in compact mode at wide viewports
--rh-color-text-secondary

A step's description color
--rh-font-family-body-text

Font family for step labels and descriptions
--rh-font-size-body-text-md

Font size for step labels
--rh-border-width-md

Icon border width
--rh-color-surface-lightest

Icon background in light mode
--rh-color-surface-darkest

Icon background in dark mode
--rh-color-gray-50

Link underline color in light mode
--rh-color-gray-40

Link underline color in dark mode
--rh-color-interactive-primary-hover

Link text color on hover

Link underline color on hover
--rh-font-weight-body-text-regular

Font weight for labels of steps

Font weight for step descriptions
--rh-font-size-body-text-xs

Font size for step descriptions
--rh-color-status-note

Icon color when step is active
--rh-color-status-success

Icon color when step is complete
--rh-color-yellow-50

Warning icon color in light mode
--rh-color-yellow-30

Warning icon color in dark mode
--rh-color-yellow-60

Warning label color in light mode
--rh-color-yellow-20

Warning label color in dark mode
--rh-color-status-danger

Icon color when step has failed

Label color when step has failed
--rh-font-weight-body-text-medium

Font weight for current/active/warn/fail step labels
Edit this page on GitHub
© 2025 Red Hat Deploys by Netlify