Timer

Installation#

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.

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.

TimerArea#

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

TimerItemGroup#

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

TimerItemLabel#

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

TimerItem#

Renders one time field from the current timer value.

TimerSeparator#

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

TimerControl#

Toolbar row for timer action controls.

TimerActionTrigger#

Button that dispatches a timer action.

TimerStart#

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

TimerPause#

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

TimerResume#

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

TimerReset#

Resets the timer to its initial startMs / idle state.

TimerRestart#

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

TimerPlay#

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

remainingMsUntilDate#

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.