Steps React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Steps is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import Steps from @/components/ui/steps.

import { useState } from "react"
import { Steps, type StepItem } from "@/components/ui/steps"

const STEPS: StepItem[] = [
  { id: "cart", title: "Cart", description: "3 items" },
  { id: "shipping", title: "Shipping", description: "FedEx" },
  { id: "payment", title: "Payment" },
  { id: "review", title: "Review" },
]

export function CheckoutSteps() {
  const [step, setStep] = useState("shipping")
  return (
    <Steps
      steps={STEPS}
      value={step}
      onValueChange={setStep}
    />
  )
}

Props

• steps*
  StepItem[]

  { id: string; title: ReactNode; description?: ReactNode; icon?: ReactNode; status?: StepStatus; optional?: boolean; disabled?: boolean; href?: string }. status overrides the derived one (complete before value, current at it, upcoming after); errors and loading are always explicit.

• value
  string

  The current step id, controlled. An id that is not among the steps leaves every step upcoming.

• defaultValuedefault ""
  string

  The starting step id while uncontrolled. Empty starts on the first step; an id that is not among the steps leaves them all upcoming. The playground takes cart, shipping, payment or review.

• onValueChange
  (id: string, step: StepItem) => void

  Fires when a clickable step is clicked.

• orientationdefault "horizontal"
  "horizontal" | "vertical"

  Vertical stacks the steps with their descriptions beside a column of markers; it works at any width.

• variantdefault "circles"
  "circles" | "bars" | "dots"

  circles: numbered markers joined by connectors (the form-wizard look). bars: one segment per step with the title under it (checkout). dots: small dots, the current one widened (onboarding).

• sizedefault "md"
  "sm" | "md" | "lg"

  Markers 24 / 28 / 32px, titles 13 / 14 / 15px, descriptions 12 / 13 / 13px.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  Paints the current marker, the tint of completed markers and the connector fill.

• colordefault ""
  string

  Any CSS color. Replaces the tone; text on the current marker turns black or white by lightness.

• labelPlacementdefault "bottom"
  "bottom" | "end"

  Horizontal circles: titles centered under the markers (clamped to two lines), or beside them with the connector after the text.

• clickabledefault "completed"
  "none" | "completed" | "all"

  Which steps are buttons: none, the ones already done (plus the current one and ones marked with an error), or every enabled step. Disabled steps never are.

• connectordefault "solid"
  "solid" | "dashed"

  dashed draws the connectors (and bar segments) still ahead as dashes.

• mobileVariantdefault "compact"
  "compact" | "same"

  Below 640px a horizontal circles or bars stepper becomes the compact header ("Step 2 of 5", title, next step, progress bar). Pure CSS: both are rendered, so the server HTML is right on a phone.

• compactdefault false
  boolean

  Always shows the compact header, at every width: phone screen headers, narrow cards, sheets. Horizontal circles and bars only (vertical and dots keep their layout).

• showDescriptiondefault true
  boolean

  Descriptions under the titles. Vertical steppers always show them.

• linkComponent
  (props: LinkComponentProps) => ReactNode

  The link component for href steps (a router Link, or "a"). Default: the one set by LinkProvider, a plain <a> without one.

• labels
  { progress?: string; step?: (position: number, count: number) => string; next?: (title: ReactNode) => ReactNode; complete?: string; current?: string; error?: string; loading?: string; optional?: string }

  Text for screen readers and the compact header. Defaults: "Progress", "Step 2 of 5", "Next: …", "Completed", "Current step", "Needs attention", "In progress", "Optional".

• classNames
  Partial<Record<"list" | "item" | "trigger" | "marker" | "title" | "description" | "connector" | "compact", string>>

  Extra classes for the inner parts.

• className
  string

  Extra classes for the root, merged last.

Parts

FAQ

Used in

More React navigation components