Countdown

The time left until a moment, in tabular figures, turning urgent under a threshold.

Web + MobileStableData display

Web and mobile — the same component for React and React Native. Stable: its API only changes in a major version.

Why it is here. Used by Orochia, krizaka.com.

When to use

For a deadline the user acts against: an auction, an offer, a live event about to start.
With the server's clock (skewMs) when the end is decided by the server.

When not to use

For a date far away: write the date (“Ends on 12 May”).
For the progress of a task.Use instead: Progress
For an elapsed time that keeps growing: format a duration in the text.

Installation

Install

npm install @krizaka/ui @krizaka/tailwind @krizaka/tokens tailwindcss

Styles

@import "tailwindcss";
@import "@krizaka/tailwind";
@import "@krizaka/ui/tailwind.css";

Import

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

Examples

Hours

Hours, minutes and seconds.

01h02m03s

Days

Days appear when there are some.

02d04h13m

Sizes

sm, md (default), lg.

01h02m03s01h02m03s01h02m03s

Urgent

Under a minute: the danger text role, the last segment pulses.

00h00m42s

With its label

showLabel: the label written before the segments.

01h02m03s

Ended

Past the target: zeros and data-ended.

00h00m00s

Props

Time left until a moment, as segments (2d 04h 13m 09s — days only when there are some) in tabular figures. Under urgentBelowMs it turns to the danger text role and its last segment pulses (no motion under prefers-reduced-motion). Words come from the app: units are the short unit labels. role="timer" without live announcements — the app announces what matters. State: data-urgent, data-ended. The urgent colour is --kz-danger-text (≥ 4.5:1 on every surface in both themes), so size="sm" is safe too.

Prop	Type	Default	Description
`label`required	`string`	—	Accessible name, e.g. "Ends in".
`target`required	`string \| number \| Date`	—	The moment it counts down to: a Date, an ISO string or epoch milliseconds.
`units`required	`CountdownUnits`	—	The short unit labels, passed translated.
`className`	`string`	—	Classes merged last, over the primitive's.
`showLabel`	`boolean`	`false`	Also show `label` before the segments, in the secondary text role (default: only read by screen readers).
`size`	`"sm" \| "md" \| "lg"`	`md`	sm · md · lg — the danger text role reads at 4.5:1 at every size, in both themes.
`skewMs`	`number`	`0`	Server clock − this clock, in milliseconds.
`urgentBelowMs`	`number`	`60000`	Below this many milliseconds it turns urgent (`text-fg-danger`, the last segment pulses). Default 60 s.

Accessibility

role="timer" named by label, without live announcements: a screen reader is not interrupted every second.
Announce the end yourself (a toast, a status) if it matters.
The pulse of the last segment stops under prefers-reduced-motion.

Best practices

Pass units and label translated: they are the app's words.
Use size="md" or larger when it can turn urgent: the danger colour is large-text safe from md.
Say what happens at zero next to it: the countdown only shows zeros.

Generated from the code of @krizaka/ui 3.8.0: its meta.ts, its examples and its types.Edit this documentation on GitHub