Skip to content
Nexus Application Design nadesign

CountdownChip

<CountdownChip> is a Badge that ticks down to a fixed deadline. Use for PII unmask windows, SLA timers, undo grace periods.

import from "@na/ui/components/CountdownChip" ▶ Open in Storybook packages/ui/src/components/CountdownChip.tsx

When to use

  • PII unmask: “auto-locks in 4:32”.
  • Workflow SLA: “12:08 to first response”.
  • Undo grace period: “Undo (5)”.
  • Anything where the user needs to see time-until a known event.

Don’t use CountdownChip for: time-since (use <time dateTime> with relative formatting), open-ended elapsed timers (no deadline = no countdown), or wall-clock displays.

Default

m:ss format. Counts down once per second; clamps to 0:00 at the deadline.

5:00 
<CountdownChip endsAt={Date.now() + 5 * 60_000} variant="secondary" />

Custom label

Pass formatLabel for any string formatting.

auto-locks in 90s 
<CountdownChip
  endsAt={Date.now() + 90_000}
  formatLabel={(ms) => `auto-locks in ${Math.ceil(ms / 1000)}s`}
  variant="outline"
/>

API

Prop Type Default Description
endsAt * number | string | Date — Absolute deadline — epoch ms, ISO string, or Date.
formatLabel (msRemaining: number) => ReactNode — Format the visible label. Default: "m:ss".
tickMs number 1000 Tick interval. Lower for sub-second precision.
onComplete () => void — Fires exactly once when remaining reaches 0.
completedLabel ReactNode — Render this when done; defaults to the formatted "0:00".
...rest BadgeProps — Variant, className, etc. — forwarded to the underlying Badge.

Design guidelines

✓ Do

  • Pair with a CTA the user can press to extend / restart the deadline (e.g. "Re-mask" next to a PII unmask CountdownChip).
  • Use destructive variant for irreversible deadlines (auto-lock, auto-cancel).
  • Set onComplete to update local state — the component does not unmount itself.

✗ Don't

  • Use CountdownChip for the wall clock. That's a different primitive entirely.
  • Tick faster than 1s for human-scale countdowns. Faster ticks waste re-renders without adding clarity.
  • Hide the chip while running. The user needs to see the deadline approaching.

Accessibility

  • Inherits Badge semantics.
  • The chip updates in place; for assistive tech, the parent region should set aria-live="polite" if the time-remaining matters for the screen-reader narration.
  • data-state flips between running and completed — useful for visual or test hooks.
  • Badge — Underlying primitive.
  • Sonner — UndoToast pattern uses a CountdownChip inside the toast.

▶ Open CountdownChip stories in Storybook