Stepper - National Design System

Best Practices

• Use steppers for multi-step forms like registration, applications, and onboarding flows where the user completes discrete stages in order
• Use the horizontal layout when you have enough width and want all steps visible at once. This is the default and works best with 3 to 5 steps
• Use the vertical layout when steps need detailed content, action buttons, or the interface is narrow (sidebars, mobile drawers). Add nds-reverse to flip progress direction from bottom-to-top, useful for timelines or chat-like flows
• Use the radial layout for compact spaces like dashboard cards or mobile headers where only the current step needs to be visible
• Use the responsive modifier classes (nds-{horizontal|vertical|radial}-{sm|md|lg}) when one flow spans multiple breakpoints. Same convention as nds-tableView-sm. The single DOM tree carrying the combined radial + linear markup morphs via JS; no parallel steppers or manual visibility switching needed
• Do not use a stepper for indeterminate or percentage-based progress. Use the Progress component instead
• Do not use a stepper for navigation menus or tab-like interfaces. Use Tabs for switching between independent content panels
• Use the dot variant when step labels are not needed and visual progress alone is sufficient, such as onboarding slides or image carousels
• Connecting lines between steps are shown by default on all steps except the last
• Keep step titles short (2 to 4 words). Use the description for additional context
• In radial steppers, add .nds-stepper-next inside the step text to preview the upcoming step name. Omit it on the final step
• Radial steppers work best with 3 to 6 steps. Fewer than 3 makes the circle progress hard to read; more than 6 makes step titles too compressed
• A horizontal stepper runs out of room on small screens. Pair it with the radial variant there: nds-radial nds-horizontal-lg is radial by default and turns horizontal from the lg breakpoint up. The same pairing works for vertical
• Use NDS.Stepper.next() for form steps, not data-stepper-control. A form step is gated by validation or by a request, and the attribute moves the stepper on every click. See Advancing the Stepper above
• Always provide a unique id on the stepper container so control buttons and the JS API can target it

Advancing the Stepper

There are three ways to move a stepper. Pick by one question: can anything refuse the move?

• Nothing can refuse it — use data-stepper-control on a button. The click moves the stepper, always. This fits a Back button, a demo, a walkthrough, and a goto that starts the flow over. It needs no JavaScript.
• Something can refuse it — call NDS.Stepper.next(id) from the code that knows the answer. Validation, a request, a server check: the thing that decides is the thing that moves the stepper. Every form step is this case.
• The step number lives in your own state — write data-current on the .nds-stepper. The component watches the attribute and re-renders. This fits a server-rendered page or a framework view that already holds the step number.

The stepper is a progress display. It never validates, never blocks, and never sends a request. A submit-typed button inside a form is handed to that form untouched: the stepper does not cancel the submit and does not move. Move it yourself once the form reports success.

JavaScript API

Steppers auto-initialize on page load. Access instances via NDS.Stepper.get(id) or call convenience methods directly. The nds:stepper:change event fires on every step change.