Countdown
A launch countdown with rolling digits that morphs into a live state at zero.
pnpm dlx shadcn@latest add @uiarc/countdownLive · keyboard ready
Fieldwork 2.0 keynote
- Keynote
- Design systems deep dive
- Live Q&A with the team
- A launch page or event hero counting to a keynote.
- A compact deadline pill in a table row or banner.
- Sale or registration windows that should flip to a Live now state on their own.
- Use stopwatch for time counting up from a start.
- Use announcement-bar when the countdown sits inside a site-wide banner with a call to action.
Installation
Add Countdown with the shadcn CLI, or copy the source by hand.
pnpm dlx shadcn@latest add @uiarc/countdownAdds the component and its local dependencies, and installs motion. First time? Add the @uiarc registry to components.json, or use the full URL:
example.tsx
import { Countdown } from "@/components/arc/countdown/countdown"; export function LaunchCountdown() { return ( <Countdown target="2026-10-06T10:00:00" timeZone="America/Los_Angeles" label="Keynote starts in" onComplete={() => router.refresh()} /> );}Compact hours and minutes
example.tsx
<Countdown variant="compact" units={["hours", "minutes"]} target={saleEndsAt} completeLabel="Ended" />API reference
2 parts. The first is the root.
Countdown
A countdown to a fixed moment with rolling digit wheels, in a large display form or a compact pill.
PropTypeDefaultDescription
targetRequiredDate | number | string–The moment to count to. Numbers are epoch ms; ISO strings with Z or an offset are exact; strings without an offset are wall time in timeZone, or UTC.timeZonestring–IANA zone for a target string without an offset, such as "America/Los_Angeles". Daylight saving is resolved for the target date.unitsCountdownUnit[]["days", "hours", "minutes", "seconds"]Units to show, sorted largest first. The largest unit absorbs the rest, so hours can pass 24 when days are left out.variant"large" | "compact""large"Large digits with unit labels, or one compact line for banners and table cells.completeLabelReactNode"Live now"Shown once the target passes, with a pulsing live dot. The digits morph into it.onComplete() => void–Fires once when the countdown reaches zero while mounted, on time even in a hidden tab.labelstring"Time remaining"Accessible name, such as "Keynote starts in".clock() => numberDate.nowClock source in epoch ms. Pass a server-synced clock when device time cannot be trusted.refRef<HTMLDivElement>–The root element.classNamestring–Class on the root.toEpoch
Resolves a countdown target to epoch ms without reading the device time zone. Returns NaN for an unparseable string.
PropTypeDefaultDescription
targetRequiredDate | number | string–Same forms as the target prop.timeZonestring–IANA zone for strings without an offset.- The root is role="timer" named by label; the visible digits are aria-hidden.
- A hidden text reads the remaining time in words, dropping seconds until under a minute so it does not chatter.
- When complete, a string completeLabel is read; other nodes read as Complete.
- Each digit is a clipped wheel that turns the short way, so 00 to 59 is one step down and the window feathers the edges.
- Digits roll in with a small stagger on first reveal, and the shell springs its width and height when a unit column appears or drops.
- At zero the digits blur and scale out into the complete label, and the live dot pulses.
- Reduced motion jumps the wheels, sizes the shell instantly, swaps with a fade, and stops the pulse.
- The large variant is a container: digits size to clamp(1.75rem, 12.5cqi, text-5xl), so four groups fit at 320px.
- The compact variant is an inline pill with 32px minimum height that springs its width as units drop.
- A single timeout wakes just after each whole second; it pauses while the tab is hidden or the countdown is off screen.
- A separate long timeout still fires onComplete on time when the tab is hidden.
- Each digit renders its whole wheel (10 or fewer glyphs), so keep a page to a few countdowns.
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
- Use for a fixed moment people wait for: a launch, a live event, a sale ending. For elapsed time use stopwatch.
- Give targets an offset or a timeZone so every visitor counts to the same instant; never rely on the visitor's zone.
- Pass clock from a server time offset when device clocks may be wrong, such as ticketed drops.
- Use variant="compact" inside announcement bars, table cells, and badges.
The full library index for assistants is at /llms.txt.