Sections

Components

Utilities

Forms

Hooks

useIsMobile

Timer

Copy Markdown

Countdown or stopwatch with controls.

Docs API

PreviewCode

Days

Hours

Minutes

Seconds

Installation#

CLIManual

pnpmbunnpmyarn

pnpm dlx shadcn@latest add @shark/timer

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.

PreviewCode

Ticks: 0

Minutes

Seconds

Orientation#

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

Vertical#

PreviewCode

minutes

seconds

Horizontal#

PreviewCode

minutes

seconds

Examples#

Countdown#

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

PreviewCode

minutes

seconds

Date-based#

Use remainingMsUntilDate to derive startMs from a calendar date.

PreviewCode

Until Jul 9, 2026

days

hours

minutes

seconds

Interval#

Use the interval prop to control update frequency.

PreviewCode

seconds

000

Pomodoro#

Alternate between work and break sessions using onComplete.

PreviewCode

🍅

Focus

Trigger Behavior

Triggers hide when their action is not available. To keep a control in the layout, pass hidden={false}.

Custom separator#

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

PreviewCode

API Reference#

Timer#

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

Prop	Type	Default
`targetMs`	`number`	`0`
`startMs`	`number`	`0`
`countdown`	`boolean`	`false`
`interval`	`number`	`1000`
`autoStart`	`boolean`	`false`
`onTick`	`(details: TickDetails) => void`	`-`
`onComplete`	`() => void`	`-`

TimerArea#

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

Prop	Type	Default
`className`	`string`	`-`
`asChild`	`boolean`	`false`

TimerItemGroup#

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

Prop	Type	Default
`orientation`	`"horizontal"	"vertical"`
`className`	`string`	`-`
`asChild`	`boolean`	`false`

TimerItemLabel#

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

Prop	Type	Default
`className`	`string`	`-`
`asChild`	`boolean`	`false`

TimerItem#

Renders one time field from the current timer value.

Prop	Type	Default
`type`	`"days"	"hours"
`asChild`	`boolean`	`false`

TimerSeparator#

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

Prop	Type	Default
`className`	`string`	`-`
`asChild`	`boolean`	`false`

TimerControl#

Toolbar row for timer action controls.

Prop	Type	Default
`className`	`string`	`-`
`asChild`	`boolean`	`false`

TimerActionTrigger#

Button that dispatches a timer action.

Prop	Type	Default
`action`	`"start"	"pause"
`hidden`	`boolean`	`-`
`asChild`	`boolean`	`false`

TimerStart#

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

Prop	Type	Default
`hidden`	`boolean`	`-`
`className`	`string`	`-`
`asChild`	`boolean`	`false`

TimerPause#

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

Prop	Type	Default
`hidden`	`boolean`	`-`
`className`	`string`	`-`
`asChild`	`boolean`	`false`

TimerResume#

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

Prop	Type	Default
`hidden`	`boolean`	`-`
`className`	`string`	`-`
`asChild`	`boolean`	`false`

TimerReset#

Resets the timer to its initial startMs / idle state.

Prop	Type	Default
`hidden`	`boolean`	`-`
`className`	`string`	`-`
`asChild`	`boolean`	`false`

TimerRestart#

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

Prop	Type	Default
`hidden`	`boolean`	`-`
`className`	`string`	`-`
`asChild`	`boolean`	`false`

TimerPlay#

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

Prop	Type	Default
`hidden`	`boolean`	`-`
`className`	`string`	`-`
`asChild`	`boolean`	`false`

`remainingMsUntilDate`#

Parameter	Type
`date`	`Date`

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.

[

Textarea ](/docs/components/textarea)[

Toast ](/docs/components/toast)

On This Page

Installation Anatomy Usage Controlled Orientation Vertical Horizontal Examples Countdown Date-based Interval Pomodoro Custom separator API Reference Timer TimerArea TimerItemGroup TimerItemLabel TimerItem TimerSeparator TimerControl TimerActionTrigger TimerStart TimerPause TimerResume TimerReset TimerRestart TimerPlay remainingMsUntilDate