ComponentsCalendar & time

Countdown

Counts down to a moment — a launch, a registration opening, a sale ending. Segmented boxes or compact inline text, the units you choose, localized unit names, and something else to show once the time is up. Server-safe: it renders dashes until the clock starts on the client.

WAI-ARIA timer role components/countdown.tsxtheme · material · accent · density · font

Registration opens in

Installation

$ pnpm add @vamos-ui/react

The whole kit as one package — get updates by bumping the version. Add the styles to globals.css: @import "@vamos-ui/react/styles.css";

Usage

import { Countdown } from "@vamos-ui/react";

<Countdown to="2027-03-01T09:00:00+03:00" label="Registration opens" highlightLast />
<Countdown variant="inline" units={["hours", "minutes", "seconds"]} to={sale.endsAt} completed="Sale ended" onComplete={refresh} />

role="timer" is not a live region and its sentence changes once a minute (every second only in the last minute), so the ticking never floods a screen reader. The digits are aria-hidden.

Announce the end yourself (or via completed, which is a status region) if people need to hear it.

Examples

Inline, with completed content

variant="inline" for banners and buttons; completed replaces the clock and onComplete fires once.

Early-bird price ends in

Units and a fixed now

The largest unit absorbs the rest (hours only → 52 h). A fixed now keeps screenshots and tests stable.

API

Countdown

PropTypeDefault
to
Target moment.
string | number | Date—
now
Fixed epoch ms for static screens and tests. Omit to tick live (every second, or every minute without a seconds unit).
number—
units
Units to show; the largest absorbs the overflow.
("days" | "hours" | "minutes" | "seconds")[]all four
variant
One box per unit with a caption, or compact text ("3d 04h 12m").
"segments" | "inline""segments"
unitDisplay
Caption style under each segment, from Intl ("days", "gün").
"long" | "short" | "narrow""long"
highlightLast
Accent fill on the last segment.
boolean—
label
What is counted down to; prefixes the accessible sentence.
string—
completed
Shown (as role="status") once the target is reached. Default: the clock at zero.
ReactNode—
onComplete
Fires once when the target is reached, also when it is already past on mount.
() => void—
labels
Dictionary namespace "countdown": remaining ("{time} left"), until ("Until {date}"), completed.
Partial<CountdownLabels>—

countdownParts(to, now, units?)

PropTypeDefault
returns
Pure split for custom layouts.
{ values, total (s), done }—
Previous
Context Menu
Next
CTA