A countdown to a date or through a duration, drawn as unit tiles whose digits roll down on the beat of each second, 9 wrapping cleanly from 0. Units are chosen per use and leading zero units can drop away, labels come from the locale in long, short or narrow form, and a message can replace the digits when time is up. It renders a stable placeholder on the server, pauses while the tab is hidden, announces the time left once a minute rather than every second, and fires onComplete once. Three tones and three sizes.
The import and the props worth knowing about, in one place.
import { TimeCountdown } from "@/components/beste/component/time-countdown";
<TimeCountdown target="2026-12-31T23:59:59Z" />
// Minutes and seconds only, as a clock with colons
<TimeCountdown duration={15 * 60} units={["minutes", "seconds"]} separator labels="none" />
<TimeCountdown
target={launchDate}
hideLeadingZeros // days disappear once under a day is left
labels="short" // "long" (default) | "short" | "narrow" | "none"
locale="de-DE"
completeLabel="We are live"
onComplete={() => console.log("Launched")}
tone="outline" // "muted" (default) | "outline" | "ghost"
size="lg" // "sm" | "default" | "lg"
/>Read from the component's own type, so this cannot drift from what it accepts.
| Prop | Type | Default | Description |
|---|---|---|---|
target | string | Date | number | — | The moment to count down to: an ISO string, a Date or a timestamp. |
duration | number | — | Seconds to count down from mount, used when there is no `target`. |
units | CountdownUnit[] | — | Which units to show, largest first. |
hideLeadingZeros | boolean | — | Drop leading units while they are zero, e.g. days once under a day is left. |
labels | "long" | "short" | "narrow" | "none" | — | How unit labels are written: "long" (days), "short" (days, abbreviated), "narrow" or "none". |
locale | string | — | Locale for the unit labels; the reader's own when omitted. |
separator | boolean | — | Put a colon between the units. |
completeLabel | string | — | Shown in place of the digits once the countdown is over. |
onComplete | () => void | — | Fires once when the countdown reaches zero. |
tone | "muted" | "outline" | "ghost" | — | |
size | "sm" | "default" | "lg" | — | |
className | string | — |