Date & Time

Countdown

Ticking day/hour/minute/second tiles counting down to a target.

Import

tsx

import { Countdown } from "@cooud-ui/ui";

bash

npx cooud-ui add countdown

Examples

Launch countdown

Days / hours / minutes / seconds tiles ticking toward a target `Date`, ISO string, or epoch-ms number. SSR-safe: a stable `--` placeholder renders until mount, then changed digits slide in (instant under reduced motion).

tsx

// Target computed once per mount. Countdown is SSR-safe on its own — it
// renders a stable "--" placeholder until mounted, so a live relative
// target causes no hydration drift.
const [target] = useState(() => Date.now() + (2 * 86_400 + 14 * 3_600 + 25 * 60 + 9) * 1_000);

return <Countdown target={target} aria-label="Launch countdown" />;

Compact with completion

`compact` shrinks the tiles for banners and toolbars, and `onComplete` fires exactly once at zero (re-arming if the target moves back into the future). Localize the captions with `labels`, e.g. `labels={{ days: "dias", hours: "horas" }}`.

Offer ends soon…

tsx

const [target, setTarget] = useState(() => Date.now() + 15_000);
const [done, setDone] = useState(false);

return (
  <div className="flex items-center gap-4">
    <Countdown compact target={target} onComplete={() => setDone(true)} aria-label="Offer ends in" />
    {done ? (
      <Button
        size="sm"
        variant="outline"
        onClick={() => {
          setDone(false);
          setTarget(Date.now() + 15_000);
        }}
      >
        Restart
      </Button>
    ) : (
      <span className="text-sm text-fg-tertiary">Offer ends soon…</span>
    )}
  </div>
);

API Reference

Generated from the component's exported types.

CountdownProps

Extends Omit<HTMLAttributes<HTMLDivElement>, "children">

Prop	Type	Default	Description
`target`*	`Date \| string \| number`	—	The moment the countdown reaches zero: a `Date`, an ISO-8601 string, or an epoch-ms number. An unparsable target keeps the `--` placeholder and never ticks or completes.
`onComplete`	`() => void`	—	Fired exactly once when the countdown reaches zero (immediately after mount when the target is already in the past). Re-arms if `target` later changes to a new future moment.
`compact`	`boolean`	`false`	Smaller tiles + type for tight spots (toolbars, banners, table cells).
`labels`	`Partial<CountdownLabels>`	—	Override any subset of the unit captions, e.g. `{ days: "dias" }`.