caliper uidocs
DemoSign inGet Pro

Countdown

Free

A live countdown to a date, in a large or compact style.

Installs components/ui/countdown.tsxDepends on none beyond ReactMotion none in component source
pnpm dlx shadcn@latest add https://caliperui.site/r/countdown.json

When to use #

Use it for

  • Launches, sales and windows that close.
  • Inside an announcement bar as the compact variant.

Skip it when

  • The time is approximate; write it out as a date.
  • Precision does not matter; use relative time text.

Installation #

terminal
pnpm dlx shadcn@latest add https://caliperui.site/r/countdown.json

Adds its 2 files to components/ui/, each with its own stylesheet, and installs their packages. No account needed. The first part also adds Caliper UI’s tokens; import them once as in Installation.

Usage #

This is the code behind the preview above. It is built from Countdown and toEpoch.

example.tsx
import { useEffect, useState } from "react"
import { Countdown } from "@/components/ui/countdown"

export function PreviewEnds() {
  const [target, setTarget] = useState<number | null>(null);
  // Chosen after mount so the server and browser render the same first frame.
  useEffect(() => {
    const id = setTimeout(() => setTarget(Date.now() + 3 * 24 * 60 * 60 * 1000 + 4 * 60 * 60 * 1000), 0);
    return () => clearTimeout(id);
  }, []);
  return target ? <Countdown target={target} label="Preview ends in" /> : null;
}

API reference #

Countdown

component
PropTypeDefault
target *string | number | Date—
unitsCountdownUnit[]order
variant"large" | "compact""large"
completeLabelReactNode"Live now"
onComplete(() => void)—
labelstring"Time remaining"
clock(() => number)Date.now
classNamestring—

toEpoch

component

No props of its own; it accepts the native props of its root element.

Accessibility #

It exposes timer semantics, with aria-hidden and aria-label kept in step with state.

No custom key handling; Tab and the native activation keys do the work.

Motion #

It declares no animation in its component source. Any transition comes from its stylesheet, which uses the duration tokens that collapse to instant under prefers-reduced-motion.