Stepper
Progress through a fixed sequence of steps, horizontal or stacked.
Use it when a task has a known number of stages in a fixed order and the reader benefits from seeing how far along they are: creating an app, onboarding a server, a setup wizard. It shows progress and does not navigate; put Back and Next buttons beside it, as the example does.
newt-stepper"use client"
import * as React from "react"
import { Button } from "@/registry/bases/newt/ui/button"
import { Stepper } from "@/registry/bases/newt/ui/stepper"
const STEPS = [
{ title: "Create the app", description: "Name and icon" },
{ title: "Add a bot", description: "Token and intents" },
{ title: "Invite it", description: "Pick a server" },
]
export default function StepperDemo() {
const [step, setStep] = React.useState(1)
return (
<div className="flex w-full max-w-lg flex-col gap-6">
<Stepper steps={STEPS} value={step} />
<div className="flex justify-center gap-2">
<Button
variant="secondary"
size="sm"
disabled={step === 0}
onClick={() => setStep(step - 1)}
>
Back
</Button>
<Button
size="sm"
disabled={step === STEPS.length}
onClick={() => setStep(step + 1)}
>
{step >= STEPS.length - 1 ? "Finish" : "Next"}
</Button>
</div>
</div>
)
}<script setup lang="ts">
import { ref } from "vue"
import { Button } from "~~/registry/bases/newt/ui/button"
import { Stepper } from "~~/registry/bases/newt/ui/stepper"
const STEPS = [
{ title: "Create the app", description: "Name and icon" },
{ title: "Add a bot", description: "Token and intents" },
{ title: "Invite it", description: "Pick a server" },
]
const step = ref(1)
</script>
<template>
<div class="flex w-full max-w-lg flex-col gap-6">
<Stepper :steps="STEPS" :value="step" />
<div class="flex justify-center gap-2">
<Button
variant="secondary"
size="sm"
:disabled="step === 0"
@click="step -= 1"
>
Back
</Button>
<Button size="sm" :disabled="step === STEPS.length" @click="step += 1">
{{ step >= STEPS.length - 1 ? "Finish" : "Next" }}
</Button>
</div>
</div>
</template>Installation
npx newtui@latest add steppernpx shadcn@latest add @newtui/steppernpx shadcn-vue@latest add @newtui/stepperpnpm dlx newtui@latest add stepperpnpm dlx shadcn@latest add @newtui/stepperpnpm dlx shadcn-vue@latest add @newtui/stepperyarn dlx newtui@latest add stepperyarn dlx shadcn@latest add @newtui/stepperyarn dlx shadcn-vue@latest add @newtui/stepperbunx newtui@latest add stepperbunx shadcn@latest add @newtui/stepperbunx shadcn-vue@latest add @newtui/stepperdeno run -A npm:newtui@latest add stepperdeno run -A npm:shadcn@latest add @newtui/stepperdeno run -A npm:shadcn-vue@latest add @newtui/steppervlx newtui@latest add steppervlx shadcn@latest add @newtui/steppervlx shadcn-vue@latest add @newtui/steppervp dlx newtui@latest add steppervp dlx shadcn@latest add @newtui/steppervp dlx shadcn-vue@latest add @newtui/steppernubx newtui@latest add steppernubx shadcn@latest add @newtui/steppernubx shadcn-vue@latest add @newtui/steppernlx newtui@latest add steppernlx shadcn@latest add @newtui/steppernlx shadcn-vue@latest add @newtui/stepperupx newtui@latest add stepperupx shadcn@latest add @newtui/stepperupx shadcn-vue@latest add @newtui/stepper- newtui
- shadcn
- npm
- pnpm
- yarn
- bun
- deno
- vlt
- vp
- nub
- ni
- upm
The shadcn CLI needs the @newtui registry in your components.json. Set it up.
Copy the source into your project
import * as React from "react"
import { cn } from "@/lib/utils"
/** One stage of the sequence. */
export interface StepperStep {
title: string
/** The quieter line under the title. */
description?: string
}
export interface StepperProps extends Omit<
React.ComponentProps<"ol">,
"children"
> {
steps: readonly StepperStep[]
/**
* Index of the step in progress. Every step before it is complete; a value
* equal to `steps.length` means all of them are.
*/
value: number
orientation?: "horizontal" | "vertical"
/** Read after a finished step's title by a screen reader. */
completedLabel?: string
}
/*
* Progress through a fixed sequence, as an ordered list. A step's state is
* said three ways, so it never rests on colour: the marker's fill, a check
* in place of the number, and `aria-current="step"` on the one in progress.
*/
const Stepper = React.forwardRef<HTMLOListElement, StepperProps>(
(
{
className,
steps,
value,
orientation = "horizontal",
completedLabel = "completed",
...props
},
ref
) => {
const vertical = orientation === "vertical"
return (
<ol
ref={ref}
data-orientation={orientation}
className={cn(
"m-0 flex w-full list-none p-0",
vertical ? "flex-col" : "gap-2",
className
)}
{...props}
>
{steps.map((step, index) => {
const complete = index < value
const current = index === value
const last = index === steps.length - 1
return (
<li
// Positional: the list is fixed, and two steps may share a title.
key={index}
aria-current={current ? "step" : undefined}
className={cn(
"relative flex min-w-0",
vertical
? "items-start gap-3 text-start"
: "flex-1 flex-col items-center gap-2 text-center",
vertical && !last && "pb-5"
)}
>
{last ? null : (
<span
aria-hidden="true"
className={cn(
"absolute rounded-full",
complete ? "bg-newt-brand" : "bg-newt-bg-active",
vertical
? "start-[13px] top-8 h-[calc(100%-36px)] w-0.5"
: "start-[calc(50%+20px)] top-[13px] h-0.5 w-[calc(100%-32px)]"
)}
/>
)}
<span
aria-hidden="true"
className={cn(
"flex h-7 w-7 shrink-0 items-center justify-center rounded-full border-2 text-[13px] font-bold",
complete
? "border-newt-brand bg-newt-brand text-newt-on-accent"
: current
? "border-newt-brand bg-newt-bg-surface text-newt-text-primary"
: "border-newt-bg-active bg-newt-bg-surface text-newt-text-muted"
)}
>
{complete ? (
<svg viewBox="0 0 16 16" className="h-4 w-4">
<path
fill="currentColor"
d="M6.2 11.6 3.1 8.5a1 1 0 0 1 1.4-1.4l1.7 1.7 4.3-4.3a1 1 0 1 1 1.4 1.4l-5 5a1 1 0 0 1-1.4 0Z"
/>
</svg>
) : (
index + 1
)}
</span>
<span
className={cn(
"flex min-w-0 flex-col gap-0.5",
vertical && "pt-1"
)}
>
<span
className={cn(
"text-sm font-semibold leading-[18px]",
complete || current
? "text-newt-text-primary"
: "text-newt-text-secondary"
)}
>
{step.title}
{complete ? (
<span className="sr-only">, {completedLabel}</span>
) : null}
</span>
{step.description === undefined ? null : (
<span className="text-xs leading-4 text-newt-text-muted">
{step.description}
</span>
)}
</span>
</li>
)
})}
</ol>
)
}
)
Stepper.displayName = "Stepper"
export { Stepper }<script setup lang="ts">
import { computed, type HTMLAttributes } from "vue"
import { cn } from "@/lib/utils"
import type { StepperStep } from "."
/*
* Progress through a fixed sequence, as an ordered list. A step's state is
* said three ways, so it never rests on colour: the marker's fill, a check
* in place of the number, and `aria-current="step"` on the one in progress.
*/
const props = withDefaults(
defineProps<{
class?: HTMLAttributes["class"]
steps: readonly StepperStep[]
/**
* Index of the step in progress. Every step before it is complete; a
* value equal to `steps.length` means all of them are.
*/
value: number
orientation?: "horizontal" | "vertical"
/** Read after a finished step's title by a screen reader. */
completedLabel?: string
}>(),
{ orientation: "horizontal", completedLabel: "completed" }
)
const vertical = computed(() => props.orientation === "vertical")
</script>
<template>
<ol
:data-orientation="props.orientation"
:class="
cn(
'm-0 flex w-full list-none p-0',
vertical ? 'flex-col' : 'gap-2',
props.class
)
"
>
<li
v-for="(step, index) in props.steps"
:key="index"
:aria-current="index === props.value ? 'step' : undefined"
:class="
cn(
'relative flex min-w-0',
vertical
? 'items-start gap-3 text-start'
: 'flex-1 flex-col items-center gap-2 text-center',
vertical && index < props.steps.length - 1 && 'pb-5'
)
"
>
<span
v-if="index < props.steps.length - 1"
aria-hidden="true"
:class="
cn(
'absolute rounded-full',
index < props.value ? 'bg-newt-brand' : 'bg-newt-bg-active',
vertical
? 'start-[13px] top-8 h-[calc(100%-36px)] w-0.5'
: 'start-[calc(50%+20px)] top-[13px] h-0.5 w-[calc(100%-32px)]'
)
"
/>
<span
aria-hidden="true"
:class="
cn(
'flex h-7 w-7 shrink-0 items-center justify-center rounded-full border-2 text-[13px] font-bold',
index < props.value
? 'border-newt-brand bg-newt-brand text-newt-on-accent'
: index === props.value
? 'border-newt-brand bg-newt-bg-surface text-newt-text-primary'
: 'border-newt-bg-active bg-newt-bg-surface text-newt-text-muted'
)
"
>
<svg v-if="index < props.value" viewBox="0 0 16 16" class="h-4 w-4">
<path
fill="currentColor"
d="M6.2 11.6 3.1 8.5a1 1 0 0 1 1.4-1.4l1.7 1.7 4.3-4.3a1 1 0 1 1 1.4 1.4l-5 5a1 1 0 0 1-1.4 0Z"
/>
</svg>
<template v-else>{{ index + 1 }}</template>
</span>
<span :class="cn('flex min-w-0 flex-col gap-0.5', vertical && 'pt-1')">
<span
:class="
cn(
'text-sm font-semibold leading-[18px]',
index <= props.value
? 'text-newt-text-primary'
: 'text-newt-text-secondary'
)
"
>
{{ step.title
}}<span v-if="index < props.value" class="sr-only"
>, {{ props.completedLabel }}</span
>
</span>
<span
v-if="step.description !== undefined"
class="text-xs leading-4 text-newt-text-muted"
>
{{ step.description }}
</span>
</span>
</li>
</ol>
</template>export { default as Stepper } from "./Stepper.vue"
/** One stage of the sequence. */
export interface StepperStep {
title: string
/** The quieter line under the title. */
description?: string
}Update the import paths
The files import @/lib/utils and sibling components through the aliases in your components.json. Point them at wherever those live in your project.
No CLI, no components.json: paste this into Claude, Cursor, Copilot or any coding assistant and it adds Stepper to your React project by hand. The prompt carries the source of every file the CLI would write — this component's and those of the components it builds on — with the imports already pointed at the default aliases.
No CLI, no components.json: paste this into Claude, Cursor, Copilot or any coding assistant and it adds Stepper to your Vue project by hand. The prompt carries the source of every file the CLI would write — this component's and those of the components it builds on — with the imports already pointed at the default aliases.
Usage
import { Stepper } from "@/components/ui/stepper"
export function Example() {
return <Stepper />
}<script setup lang="ts">
import { Stepper } from "@/components/ui/stepper"
</script>
<template>
<Stepper />
</template>API reference
Stepper
steps?{ title: string; description?: string }[]
The stages, in order.
{ title: string; description?: string }[]value?number
Index of the step in progress. Every step before it is complete, and a value equal to `steps.length` marks them all complete.
numberorientation?"horizontal" | "vertical"
`vertical` stacks the steps with the marker beside the text, for a narrow column.
"horizontal" | "vertical""horizontal"completedLabel?string
Read by a screen reader after the title of a finished step.
string"completed"Three to five steps fit a horizontal stepper. Past that, or in a sidebar, use orientation="vertical".
Accessibility
The steps are an ordered list, so their count and order are announced. The step in progress carries aria-current="step", and a finished step’s title is followed by the hidden word from completedLabel. State is never carried by colour alone: a finished step shows a check where its number was, and the current one has a filled outline.
completedLabel defaults to completed. Translating labels lists every English default.
Tokens
Stepper reads its colours, radii and motion from the --newt-* tokens installed with the library. Override a token and every component that reads it follows, including this one — see the token layer. In the plain HTML and CSS distribution the same component is newt-stepper.
--newt-radius-full--newt-bg-active--newt-brand--newt-bg-surface--newt-text-muted--newt-text-primary--newt-on-accent--newt-text-secondary