Steps

Example

<ol data-slean="steps" aria-label="Checkout">
	<li>
		<span data-slean-part="title">Cart</span>
		<span data-slean-part="complete">Completed</span>
	</li>
	<li aria-current="step">
		<span data-slean-part="title">Shipping</span>
		<span data-slean-part="description">Address and delivery date</span>
	</li>
	<li>
		<span data-slean-part="title">Payment</span>
		<span data-slean-part="description">Card or invoice</span>
	</li>
	<li><span data-slean-part="title">Review</span></li>
</ol>

<script lang="ts">
	// Nothing to import at runtime: the steps are a list. The stylesheet is optional.
	import '@svelte-lean/styles/steps.css';
</script>

<ol data-slean="steps" aria-label="Checkout">
	<li>
		<span data-slean-part="title">Cart</span>
		<span data-slean-part="complete">Completed</span>
	</li>
	<li aria-current="step">
		<span data-slean-part="title">Shipping</span>
		<span data-slean-part="description">Address and delivery date</span>
	</li>
	<li>
		<span data-slean-part="title">Payment</span>
		<span data-slean-part="description">Card or invoice</span>
	</li>
	<li><span data-slean-part="title">Review</span></li>
</ol>

Why this implementation exists

A stepper is an ordered list with a current item: the <ol> gives each step its position (“2 of 4”) and aria-current="step" marks where the reader is. Neither needs a script.

The state that markup usually loses is “complete”: a check drawn for sighted readers and nothing for a screen reader. Here the complete state is one element, a text that says “Completed”, hidden visually and read aloud; steps.css draws the check from that same element with :has(), so what is seen and what is heard cannot disagree.

Usage

The markup needs no package. Install @svelte-lean/styles for the stylesheet; @svelte-lean/primitives adds the typed contract and nothing at runtime.

npm install @svelte-lean/styles

pnpm add @svelte-lean/styles

yarn add @svelte-lean/styles

bun add @svelte-lean/styles

import '@svelte-lean/styles/steps.css';

Render one <li> per step, aria-current="step" on the current one, and the complete part in every step that is done. Write the complete text in the language of the page.

A step that can be revisited holds a link. When the steps navigate a multi-page form, wrap the list in a named <nav>.

Anatomy

Runtime profile

Tier 0: the steps have no behavior module, the Vite plugin maps steps to no module, and the page ships no Svelte Lean JavaScript for them.

Accessibility contract

• An <ol>: screen readers announce each step’s position.
• aria-current="step" on the current step.
• The complete part is text, clipped to one pixel and read after the step’s title.
• The step number is generated content with empty alternative text, so the position is not read twice.

Keyboard

Platform features

Without JavaScript

Fully functional: the list and its states are markup.

Server rendering

Static markup: the server renders the current and complete states from the task’s state.

Before hydration

Nothing is attached; the list is the same before and after hydration.

Styling

steps.css numbers the steps with a counter in a ring (li::before), draws the connector to the next step (li::after), fills the current step’s ring with the accent, and draws a check in the soft accent for a step that contains the complete part, from two gradients in the turned ring. data-slean-orientation="vertical" moves the connector below the ring. Under forced colors the rings and connectors use system colors. The tokens it reads:

State selectors the stylesheet targets, all from the platform or ARIA: :last-child, [aria-current="step"].

Variant attributes: data-slean-orientation (vertical).

Controlled integration

The application owns the step index; the markup follows it. Every step before the current one gets the complete part.

<script lang="ts">
	// The application owns the step index; the markup follows it.
	let { current }: { current: number } = $props();
	const steps = ['Cart', 'Shipping', 'Payment', 'Review'];
</script>

<ol data-slean="steps" aria-label="Checkout">
	{#each steps as title, i (title)}
		<li aria-current={i === current ? 'step' : undefined}>
			<span data-slean-part="title">{title}</span>
			{#if i < current}<span data-slean-part="complete">Completed</span>{/if}
		</li>
	{/each}
</ol>

Compatibility notes

The list, aria-current and counters are widely available. :has() (Baseline 2023) draws the complete state; without it a complete step looks like an upcoming one and its text is still read. Alternative text for generated content is Baseline 2024; without it a screen reader may read the number with the step. The check is turned with the rotate property (Baseline 2022).

Examples

Vertical

data-slean-orientation="vertical" stacks the steps with the connector below each indicator. It suits long titles, descriptions and narrow columns; the semantics do not change.

<ol data-slean="steps" data-slean-orientation="vertical" aria-label="Onboarding">
	<li>
		<span data-slean-part="title">Create the workspace</span>
		<span data-slean-part="description">harbor.studio</span>
		<span data-slean-part="complete">Completed</span>
	</li>
	<li>
		<span data-slean-part="title">Invite the team</span>
		<span data-slean-part="description">Four people joined</span>
		<span data-slean-part="complete">Completed</span>
	</li>
	<li aria-current="step">
		<span data-slean-part="title">Connect a repository</span>
		<span data-slean-part="description">Pull requests appear in the review queue</span>
	</li>
	<li><span data-slean-part="title">Plan the first sprint</span></li>
</ol>

Testing

• apps/playground/tests/primitives/feedback-navigation.spec.ts Playwright: roles, names and states in the accessibility tree, keyboard, RTL, reduced motion, axe
• packages/styles/tests static checks of the stylesheet (layers, tokens, specificity, dark parity)

Source

• packages/primitives/src/steps/contract.md the contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behavior
• packages/primitives/src/steps/contract.ts typed constants: name, tier, base, parts, options, events
• packages/styles/css/steps.css the optional stylesheet