Loading…

Countdown

beta

A countdown to a date whose days, hours, minutes and seconds roll digit by digit, compact or as labelled tiles.

Display
1 file
1 npm package
Accessibility notes

Playground

Installation

The CLI installs number-flow as well, because this component imports it. Or copy everything in by hand.

$pnpm dlx @dowel-ui/cli add countdown

npm packages installed: class-variance-authority.

Usage

Imported from your own path — the file is yours, so this is an import like any other.

app/page.tsxTSX

import { Countdown } from "@/components/ui/countdown";

Examples

Every example the tests run, live and operable, side by side.

Default
Labelled
Completing
Fixed Units
Localised
Injected Clock

API

Generated from the component's own types, so a prop cannot appear here without existing.

<Countdown>

Prop	Type	Default
`date` (required) The moment to count down to. A string is parsed with Date.parse.	`Date \| number \| string`	—
`format`	`"compact" \| "labelled"`	`"compact"`
`labels` Captions and screen-reader sentences, for translation.	`CountdownLabels`	—
`live` Announce the remaining time politely as it changes — at most once a minute. Off by default.	`boolean`	`false`
`locales` Locale for unit names and digits. Defaults to the user's.	`Intl.LocalesArgument`	—
`now` The current time. Set it to drive the countdown yourself, to render a definite value on the server, or in tests; while it is set the component does not tick on its own.	`Date \| number`	—
`onComplete` Called once when the countdown reaches zero — including when `date` has already passed.	`() => void`	—
`units` Which units to show, largest first. `auto` (default) drops leading units that are zero, down to minutes and seconds. A fixed list always shows its units, with the largest absorbing any hidden larger ones.	`"auto" \| readonly CountdownUnit[]`	`"auto"`

Plus every attribute of <div> except children.

Accessibility

role="timer" with aria-live off: a timer that spoke every second would drown out everything else. The rolling digits are aria-hidden; assistive technology reads one sentence — "2 days, 3 hours, and 4 minutes remaining" — as text content, which changes at most once a minute. `live` makes that sentence (and only that sentence) a polite live region. Unit names are localised through Intl; the surrounding sentences are in `labels`. Before hydration the digits are dashes and the sentence is empty, so server and client agree. Under reduced motion the digits change without rolling.

Quality

Measured from the source and its tests at build time.

All scores

7/7

checks passed

Tested — passes
axe assertion — passes
Keyboard tested — does not apply
Storybook examples — passes
Accessibility documented — passes
Semantic tokens only — passes
Motion from tokens — does not apply
className merged — passes
Visible focus — does not apply
No fixed widths — passes

Prop

Type

Default

date

The moment to count down to. A string is parsed with Date.parse.

Date | number | string

—

format

"compact" | "labelled"

"compact"

labels

Captions and screen-reader sentences, for translation.

CountdownLabels

—

live

Announce the remaining time politely as it changes — at most once a minute. Off by default.

boolean

false

locales

Locale for unit names and digits. Defaults to the user's.

Intl.LocalesArgument

—

now

The current time. Set it to drive the countdown yourself, to render a definite value on the server, or in tests; while it is set the component does not tick on its own.

Date | number

—

onComplete

Called once when the countdown reaches zero — including when date has already passed.

() => void

—

units

Which units to show, largest first. auto (default) drops leading units that are zero, down to minutes and seconds. A fixed list always shows its units, with the largest absorbing any hidden larger ones.

"auto" | readonly CountdownUnit[]

"auto"