Feature request: New Stepper component for Vaadin 26

[letrthang]

Motivation

When building multi-step workflows such as checkout processes, setup wizards, long forms, or any guided flow, applications need to present a sequence of steps to the user — showing one step at a time while keeping the user oriented about their progress.

Vaadin currently has no first-class component for this. Developers must hand-roll the UI using HorizontalLayout, Button, ProgressBar, and custom logic, which is repetitive, error-prone, and inconsistent across applications.

Proposed Component: Stepper

A new Stepper component that displays a series of steps and shows them one at a time.

Core behavior

┌─────────────────────────────────────────────────┐
│  ● Step 1 ──── ○ Step 2 ──── ○ Step 3           │  ← progress indicator
├─────────────────────────────────────────────────┤
│                                                 │
│              [ content of current step ]         │  ← content area (one at a time)
│                                                 │
├─────────────────────────────────────────────────┤
│                          [ Previous ]  [ Next ] │  ← navigation
└─────────────────────────────────────────────────┘

• Renders a list of steps, displaying only the current step's content at any time.
• A visual progress indicator shows which steps are completed, current, and upcoming.
• Navigation controls (Previous / Next, or linear/non-linear modes).

Suggested API

Stepper stepper = new Stepper();

stepper.addStep(new Step("Account", accountForm));   // label + content component
stepper.addStep(new Step("Address", addressForm));
stepper.addStep(new Step("Review",  reviewLayout));

stepper.setLinear(true);          // must complete steps in order
stepper.setNavigable(false);      // user cannot jump to arbitrary step

stepper.addCompletedListener(e -> {
    // all steps finished
    Notification.show("Done!");
});

Key features

Feature	Description
Step states	UPCOMING, CURRENT, COMPLETED, ERROR
Linear / Non-linear	Linear forces sequential navigation; non-linear allows free jumping
Validation hooks	BeforeNextListener to validate before advancing to the next step
Progress indicator	Horizontal (default) and vertical orientation for the step list
Label & icon	Each step can have a text label, an icon, or both
Programmatic control	next(), previous(), goTo(index), getCurrentStep()
Responsive	Collapses the indicator to a simple "Step X of N" on narrow screens
Theme variants	Lumo theme variants for different visual densities

Alternatives considered

• Manual composition (the current workaround): every team rebuilds this with HorizontalLayout + Button + custom state tracking. Inconsistent UX across apps, duplicated effort, and no built-in accessibility.
• Third-party add-ons: some community add-ons exist but are not maintained to the same standard as core components and lack proper Lumo theming/internationalization.

A built-in Stepper would standardise this extremely common pattern across all Vaadin applications.

Prior art

This is a well-established UI pattern in virtually every major UI framework:

• Material UI (React) — Stepper
• Ant Design (React) — Steps
• Angular Material — Stepper
• PrimeFaces / PrimeNG — Steps / Stepper
• Fluent UI — breadcrumb-style stepper

Accessibility

A first-class component can ensure correct ARIA semantics out of the box (aria-current, role="progressbar", keyboard navigation between steps) — something that is very hard to get right when hand-rolled.

---

I'd be happy to help refine the API or contribute a prototype. Is this something the team would consider for Vaadin 26?

[Artur-]

Related to vaadin/web-components#5582