Media & time

Countdown

A countdown to a fixed moment.

Client componentSource

Import

import { Countdown } from '@the_viveksingh/vivek-ui'

Time until an event

Pass now to pin the reference time. That is what makes a countdown testable and keeps server and client markup identical on the first paint.

2 days, 21 hours, 30 minutes, 0 seconds

Pass `now` to pin the reference time, which is what makes a countdown testable and keeps server and client markup identical.

<Countdown to={launchDate} label="Time until v1.0" />

Pick the units

69 hours, 30 minutes, 0 seconds
2 days, 21 hours, 30 minutes, 0 seconds
<Countdown to={launchDate} format={['hours', 'minutes', 'seconds']} showLabels={false} />
<Countdown to={launchDate} hideZeroUnits label="Time until launch" />

Props

Generated from the package's own type declarations, so this table cannot drift from the code.

Props for Countdown
PropTypeDefaultDescription
to requiredDate | string | number—The moment being counted down to.
formatreadonly CountdownUnit[]—Which units to show. Order is normalised largest-first. Defaults to all four.
onComplete() => void—Fired once, when the countdown reaches zero.
showLabelsboolean—Show the word under each number. Defaults to `true`.
hideZeroUnitsboolean—Drop leading units that are still zero.
nowDate | string | number—The clock for the FIRST render, on both sides of hydration. Pass a server timestamp and the server HTML contains real numbers that the client reproduces exactly. Omit it and the first render is a `--` placeholder instead: the component refuses to read the clock during render, because a server that renders at 12:00:03 and a browser that hydrates at 12:00:05 would produce different HTML and React would discard it with a hydration error.
labelsPartial<Record<CountdownUnit, string>>—Override the visible unit words, e.g. for another language.
labelstring—Accessible name of the timer. Defaults to `'Time remaining'`.
completeLabelstring—Announced instead of the digits once the countdown finishes.

Every remaining prop is spread onto the root element, so all standard HTML and ARIA attributes work. className and style are merged with the library's own, never replaced, and the ref forwards to the root DOM node.

Rendering