Stepper

Stepper for a useful, keyboard-friendly product interface.

Make it yours.

Install the editable source and its dependencies into your React + Tailwind project.

Scroll horizontally for long lines

pnpm dlx shadcn@4.0.8 add http://localhost:3000/r/stepper.json

Use it

Scroll horizontally for long lines

"use client";
import { Stepper } from "@/components/jez-ui/ui/stepper";

export default function Example() {
  return (
    <>
      <div className="w-full max-w-sm">
        <div className="mb-7">
          <h3 className="text-2xl tracking-tight">One thing at a time.</h3>
          <p className="mt-2 text-sm leading-relaxed text-muted-foreground">
            A few small steps to make yourself at home.
          </p>
        </div>
        <Stepper
          steps={["Your details", "Workspace", "Ready"]}
          current={1}
        />
      </div>
    </>
  );
}

Compose your own

These styled parts are included in the same install. Use children to build your layout; add className only when you want an override.

Scroll horizontally for long lines

import { Stepper, StepperItem, StepperIndicator, StepperTitle, StepperDescription } from "@/components/jez-ui/ui/stepper";

Read the composition guide →

Props & types

Scroll horizontally for long lines

React.ComponentProps<"ol"> & { steps?: string[]; current?: number }

Source

View 2 source files

registry/ui/stepper.tsx

Scroll horizontally for long lines

"use client";
import * as React from "react";
import { cn } from "./utils";
export function Stepper({
  steps,
  current = 0,
  children,
  className,
  ...props
}: React.ComponentProps<"ol"> & { steps?: string[]; current?: number }) {
  return (
    <ol className={cn("flex flex-wrap gap-5", className)} {...props}>
      {steps
        ? steps.map((label, i) => (
            <StepperItem
              key={label}
              state={
                i === current
                  ? "current"
                  : i < current
                    ? "complete"
                    : "upcoming"
              }
            >
              <StepperIndicator>{i + 1}</StepperIndicator>
              <StepperTitle>{label}</StepperTitle>
            </StepperItem>
          ))
        : children}
    </ol>
  );
}
export function StepperItem({
  state = "upcoming",
  className,
  ...props
}: React.ComponentProps<"li"> & {
  state?: "current" | "complete" | "upcoming";
}) {
  return (
    <li
      data-state={state}
      aria-current={state === "current" ? "step" : undefined}
      className={cn("group/step flex items-center gap-3 text-sm", className)}
      {...props}
    />
  );
}
export function StepperIndicator({
  className,
  ...props
}: React.ComponentProps<"span">) {
  return (
    <span
      className={cn(
        "grid size-7 shrink-0 place-items-center rounded-full bg-muted text-xs group-data-[state=current]/step:bg-primary group-data-[state=current]/step:text-primary-foreground group-data-[state=complete]/step:bg-primary group-data-[state=complete]/step:text-primary-foreground",
        className,
      )}
      {...props}
    />
  );
}
export function StepperTitle({
  className,
  ...props
}: React.ComponentProps<"span">) {
  return (
    <span
      className={cn(
        "text-muted-foreground group-data-[state=current]/step:font-medium group-data-[state=current]/step:text-foreground",
        className,
      )}
      {...props}
    />
  );
}
export function StepperDescription({
  className,
  ...props
}: React.ComponentProps<"p">) {
  return (
    <p
      className={cn(
        "mt-1 text-xs leading-relaxed text-muted-foreground",
        className,
      )}
      {...props}
    />
  );
}

registry/ui/utils.ts

Scroll horizontally for long lines

import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";
export function cn(...values: ClassValue[]) {
  return twMerge(clsx(values));
}

Dependencies

clsx@2.1.1 · tailwind-merge@3.5.0

Accessibility & behaviour

Provide meaningful labels and preserve keyboard focus styles. Check contrast when customising theme colours.

Read the accessibility and performance guide →