Step Dots

Preview

Install

1. 1. Add the registry to components.json, once per app. Without it, the shadcn CLI looks up @txbrendan in a public list that txbrendan/ui does not control.

   npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json"

2. 2. Add the theme, once per app. It replaces your color tokens with ones checked for contrast.

   npx shadcn@latest add @txbrendan/theme

3. 3. Add the component.

   npx shadcn@latest add @txbrendan/step-dots

Props

• steps

  One name per step, in order. Screen readers read each name with 'Step 2 of 4' and its state.

  readonly string[]

• current

  The current step, counted from 0. Steps before it are done. Set it to steps.length when all are done. Use it with onCurrentChange.

  number

• defaultCurrent

  The first current step when you do not control it.

  number · default 0

• onCurrentChange

  Called with the step someone clicked. Clicking the current step does not call it.

  (index: number) => void

• jump

  Which dots are buttons. back: done steps and the current one. any: every step. none: no buttons.

  "none" | "back" | "any" · default "none"

• tone

  Color of the done and current dots.

  "neutral" | "brand" | "danger" | "success" | "warning" · default "neutral"

• aria-label

  Names the list. Pass a better name, like 'Setup progress'. With aria-labelledby set, the default is dropped.

  string · default "Progress"

• stepText

  What screen readers hear for each step. {step} is its place, {total} the number of steps, {name} its name, and {state} a word from stateText.

  string · default "Step {step} of {total}: {name}, {state}"

• stateText

  The words for {state} in stepText.

  { done: string; current: string; upcoming: string } · default { done: "done", current: "current", upcoming: "upcoming" }

• className

  Extra classes for the list. Later classes win, so className='[--step-dots-size:6px]' makes the dots smaller.

  string

Accessibility

• Renders an <ol>, so screen readers say how many steps there are.
• Each step has hidden text, like 'Step 2 of 4: Profile, current'. stepText and stateText change the words. The dots themselves are hidden from screen readers.
• The current step has aria-current="step".
• With jump on, a clickable step is a native <button>, so Tab, Enter, and Space work. Steps people cannot reach are not buttons.
• The current step stays a button while jump is on, so focus stays on the dot someone pressed when it becomes current.
• Each dot sits in a cell at least 24px square, the smallest click target WCAG 2.2 allows.
• The current dot is a wider pill, so it is not marked by color alone. Done dots use the tone fill and upcoming dots use --input. The theme tests hold both to 3:1 on the page and on cards.
• The pill grows and shrinks over --motion-duration-base. data-motion="off" makes it instant. Reduced motion keeps the color change and drops the change of width.

Examples

<StepDots
  aria-label="Setup progress"
  steps={["Account", "Profile", "Team", "Invite"]}
  current={1}
/>

"use client";
import { useState } from "react";

const steps = ["Cart", "Shipping", "Payment", "Review"];

function CheckoutSteps() {
  const [step, setStep] = useState(2);
  return (
    <StepDots
      aria-label="Checkout progress"
      steps={steps}
      current={step}
      onCurrentChange={setStep}
      jump="back"
      tone="brand"
    />
  );
}

const steps = ["Account", "Profile", "Team"];

<StepDots aria-label="Setup progress" steps={steps} current={steps.length} tone="success" />

<StepDots
  aria-label="Fortschritt der Einrichtung"
  steps={["Konto", "Profil", "Team", "Einladen"]}
  current={1}
  stepText="Schritt {step} von {total}: {name}, {state}"
  stateText={{ done: "erledigt", current: "aktuell", upcoming: "offen" }}
/>