Step Player 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

Usage

Import StepPlayer from @/components/ui/step-player.

"use client"

import { useState } from "react"
import { StepPlayer } from "@/components/ui/step-player"

export function Demo() {
  return <StepPlayer steps={5} duration={3000} />
}

// drive your own carousel off the index
const slides = ["Welcome", "Invite your team", "Ship it"]

export function Carousel() {
  const [index, setIndex] = useState(0)

  return (
    <div className="grid gap-4">
      <p className="text-lg font-medium">{slides[index]}</p>
      <StepPlayer steps={slides.length} value={index} onValueChange={setIndex} loop />
    </div>
  )
}

Props

• stepsdefault 4
  number | StepPlayerStep[]

  How many steps to show. Pass an array of { duration?, label? } to give each one its own duration or accessible label.

• sizedefault 48
  number

  Height of the track and button in pixels (minimum 12). Every other dimension is a fixed ratio of it, so the dots, bar, gaps, padding, icon, and tap targets all scale from this one number.

• controlPositiondefault "right"
  "left" | "right"

  Which side of the track the button sits on.

• showControldefault true
  boolean

  Shows the round play button. Turn it off for a track on its own and drive it with the playing prop.

• trackColordefault ""
  string

  Any CSS color for the pill track and the round control. Empty uses #F4F4F9 light, #262626 dark.

• fillColordefault ""
  string

  Any CSS color for finished steps and the running fill. Empty uses #3C3C43 light, #EBEBF5 dark.

• pendingColordefault ""
  string

  Any CSS color for the steps still to come.

• iconColordefault ""
  string

  Any CSS color for the play, pause and replay glyph and the focus outline. Empty uses #868593.

• durationdefault 4000
  number

  Milliseconds each step runs for. A per-step duration overrides it; 0 stops the timer so you can drive the index yourself.

• loopdefault false
  boolean

  Wraps back to the first step instead of stopping. The replay button never appears when this is on.

• seekabledefault false
  boolean

  Lets a step be clicked to jump to it (and starts playing from there). The dots keep a finger-sized tap target at every size.

• playLabeldefault "Play"
  string

  Accessible name of the control while paused.

• pauseLabeldefault "Pause"
  string

  Accessible name of the control while playing.

• replayLabeldefault "Replay"
  string

  Accessible name of the control after the last step.

• positionLabeldefault "Step {index} of {count}"
  string

  Accessible name of the track; {index} and {count} fill in.

• stepLabeldefault "Step {index}"
  string

  Accessible name of each seek target when seekable and a step has no label; {index} fills in.

• defaultValuedefault 0
  number

  Step to start on when uncontrolled. Clamped to the last step.

• defaultPlayingdefault false
  boolean

  Whether the sequence starts running on mount when uncontrolled.

• value
  number

  Active step index, for controlled use. Leave it out and the component tracks its own index.

• onValueChange
  (value: number) => void

  Fires when the step advances, wraps, or is clicked. Also fires on replay.

• playing
  boolean

  Play state, for controlled use. Leave it out to let the button drive it.

• onPlayingChange
  (playing: boolean) => void

  Fires when the button is pressed, when a step is clicked, and when the last step ends without loop.

• onComplete
  () => void

  Fires when the last step finishes, on every pass when looping.

• className
  string

  Extra classes merged onto the root element (data-slot="step-player"). It sizes itself from the size prop, so give it a width only if you want the track wider than its content. Other div props are spread onto it too.

Parts

FAQ

More React media components