Skip to content
shadcn.io is not affiliated with official shadcn/ui

Shadcn Timer for React and Tailwind

Countdown or stopwatch with controls.

00
Days
00
Hours
00
Minutes
00
Seconds

Installation

bunx --bun shadcn@latest add https://kit.dev/r/timer.json

Anatomy

Timer
├── TimerArea
│   ├── TimerItemGroup
│   │   ├── TimerItem
│   │   └── TimerItemLabel
│   ├── TimerSeparator
└── TimerControl
    ├── TimerActionTrigger
    ├── TimerStart
    ├── TimerPause
    ├── TimerResume
    ├── TimerReset
    ├── TimerRestart
    └── TimerPlay

Usage

import {
  Timer,
  TimerArea,
  TimerItem,
  TimerItemGroup,
  TimerItemLabel,
  TimerSeparator,
  TimerControl,
  TimerActionTrigger,
  TimerStart,
  TimerPause,
  TimerResume,
  TimerReset,
  TimerRestart,
  TimerPlay,
} from "@/components/ui/timer";
<Timer targetMs={3600000} startMs={2400000}>
  <TimerArea>
    <TimerItemGroup>
      <TimerItem type="hours" />
      <TimerItemLabel>Hours</TimerItemLabel>
    </TimerItemGroup>
    <TimerSeparator />
    <TimerItemGroup>
      <TimerItem type="minutes" />
      <TimerItemLabel>Minutes</TimerItemLabel>
    </TimerItemGroup>
    <TimerSeparator />
    <TimerItemGroup>
      <TimerItem type="seconds" />
      <TimerItemLabel>Seconds</TimerItemLabel>
    </TimerItemGroup>
  </TimerArea>
  <TimerControl>
    <TimerPlay>Go</TimerPlay>
    <TimerPause>Pause</TimerPause>
    <TimerReset>Reset</TimerReset>
  </TimerControl>
</Timer>

Controlled

Handle onTick and onComplete to react to timer progress and completion.

Orientation

Use the orientation prop on TimerItemGroup to change the orientation of the timer.

Vertical

Horizontal

Examples

Countdown

Create a countdown by setting countdown to true and startMs to the initial duration.

Date-based

Use remainingMsUntilDate to derive startMs from a calendar date.

Interval

Use the interval prop to control update frequency.

Pomodoro

Alternate between work and break sessions using onComplete.

Custom separator

Pass children to TimerSeparator to override the default colon (:).

API Reference

Timer

Root component. Runs a stopwatch or countdown and provides timer state to child parts.

PropTypeDefault
targetMsnumber0
startMsnumber0
countdownbooleanfalse
intervalnumber1000
autoStartbooleanfalse
onTick(details: TickDetails) => void-
onComplete() => void-

TimerArea

Live region that exposes the formatted time to assistive tech and lays out digit groups.

PropTypeDefault
classNamestring-
asChildbooleanfalse

TimerItemGroup

Groups a TimerItem with its TimerItemLabel and sets stack direction via orientation.

PropTypeDefault
orientation"horizontal" | "vertical""vertical"
classNamestring-
asChildbooleanfalse

TimerItemLabel

Caption for the adjacent TimerItem (for example, “minutes”).

PropTypeDefault
classNamestring-
asChildbooleanfalse

TimerItem

Renders one time field from the current timer value.

PropTypeDefault
type"days" | "hours" | "minutes" | "seconds" | "milliseconds""seconds"
asChildbooleanfalse

TimerSeparator

Visual delimiter between item groups (defaults to : when children are omitted).

PropTypeDefault
classNamestring-
asChildbooleanfalse

TimerControl

Toolbar row for timer action controls.

PropTypeDefault
classNamestring-
asChildbooleanfalse

TimerActionTrigger

Button that dispatches a timer action.

PropTypeDefault
action"start" | "pause" | "resume" | "reset" | "restart""start"
hiddenboolean-
asChildbooleanfalse

TimerStart

Starts the timer. Wraps TimerActionTrigger with action="start".

PropTypeDefault
hiddenboolean-
classNamestring-
asChildbooleanfalse

TimerPause

Pauses a running timer. Wraps TimerActionTrigger with action="pause".

PropTypeDefault
hiddenboolean-
classNamestring-
asChildbooleanfalse

TimerResume

Resumes from paused. Wraps TimerActionTrigger with action="resume".

PropTypeDefault
hiddenboolean-
classNamestring-
asChildbooleanfalse

TimerReset

Resets the timer to its initial startMs / idle state.

PropTypeDefault
hiddenboolean-
classNamestring-
asChildbooleanfalse

TimerRestart

Restarts the timer. Wraps TimerActionTrigger with action="restart".

PropTypeDefault
hiddenboolean-
classNamestring-
asChildbooleanfalse

TimerPlay

Shorthand for a single "go" control: renders TimerResume when the timer is paused, otherwise TimerStart.

PropTypeDefault
hiddenboolean-
classNamestring-
asChildbooleanfalse

remainingMsUntilDate

ParameterType
dateDate

Returns a number of milliseconds until date, or 0 if date is in the past.


For a complete list of props, see the Ark UI documentation.