Countdown React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Countdown is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import Countdown from @/components/ui/countdown.

import { Countdown } from "@/components/ui/countdown"
import { toast } from "@/components/ui/toast"

export function LaunchCountdown() {
  return (
    <Countdown
      to="2026-09-26T20:52:09+03:00"
      size="lg"
      completedContent="Acme CRM 4.0 is live"
      onComplete={() => toast.success("The launch has started")}
      // labels: plural functions per unit, e.g. days: (count, formatted) => `${formatted} ${count === 1 ? "day" : "days"}`
    />
  )
}

Props

• to*
  Date | number | string

  The moment to count down to: a Date, ms since epoch or an ISO string. An invalid value renders the done state and logs nothing. Changing it recomputes at once and re-arms onComplete. The playground sets it through the buttons under the card.

• now
  Date | number

  Pins the clock (demos, screenshots, server rendering). Left out, the live clock ticks exactly on the unit boundaries of `to` (and re-syncs when the tab wakes); until it is known after hydration the digits render as -- at their final width.

• unitsdefault "auto"
  CountdownUnit[] | "auto"

  auto shows days, hours, minutes and seconds and drops leading zero units (never "0 days"), always keeping the last two. An explicit list like ["hours", "minutes"] folds the rest into the largest unit (52 hours).

• variantdefault "blocks"
  "blocks" | "inline" | "text"

  blocks: a tile per unit with its label under it. inline: 2d 04:12:09 in the flow of a sentence. text: words, "in 2 days and 4 hours", built from labels.

• sizedefault "md"
  "sm" | "md" | "lg"

  blocks: 40 / 56 / 80px tiles with 20 / 28 / 44px numerals (lg shrinks to 36px numerals below 400px so four units fit a 360px phone). inline 13 / 15 / 20px, text 13 / 14 / 16px.

• animationdefault "roll"
  "roll" | "fade" | "none"

  roll: odometer wheels from AnimatedCounter. fade: each changed digit crossfades in place. none: plain text. Reduced motion always behaves as none.

• tileVariantdefault "soft"
  "soft" | "solid" | "outline" | "elevated"

  The look of the tiles in blocks: a tint, a solid fill, a hairline outline, or a raised card surface.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  Semantic color of the tiles and digits. neutral is a quiet foreground tint. It never changes on its own near the end; style [data-urgent] if you want that.

• colordefault ""
  string

  Any CSS color. Replaces the tone; text on a solid tile turns black or white by lightness.

• radiusdefault "md"
  "none" | "sm" | "md" | "lg" | "full"

  Corner shape of the tiles and the done box, scaled with the size (md is 12 / 16 / 24px).

• showLabelsdefault true
  boolean

  Unit names under the blocks; in inline the letter after the days (2d). Without labels, blocks show the separator between tiles.

• showSecondsdefault true
  boolean

  false hides seconds and ticks once a minute: calmer, and cheaper on long lists of cards.

• padStartdefault true
  boolean

  04 instead of 4 for hours, minutes and seconds. Days are never padded and grow past 99 without a cap.

• separatordefault ":"
  string

  Between units in inline, and between tiles in blocks when showLabels is off. An empty string in inline gives every unit its letter: 2d 4h 12m 09s.

• precisiondefault 2
  number

  text variant: how many units the phrase names, largest first ("in 3 days and 4 hours").

• aligndefault "center"
  "start" | "center" | "end"

  blocks: where the row sits in its container (the blocks root is full width).

• completedContentdefault ""
  ReactNode

  Replaces the digits when time is up, like "The offer has ended", springing in on a bouncy scale. Without it the digits stay at zero. Try it with "in 10 s".

• localedefault ""
  string

  Locale for the digits and the plural rules your labels use. Empty follows UIProvider, then the page.

• onComplete
  () => void

  Fires once on the transition to zero while mounted, on time even when seconds are hidden. A to already past at mount renders done without calling it.

• intervaldefault 0
  number

  ms between ticks (at least 1000), aligned to the target so the last tick lands exactly at zero. Unset (0) ticks every second, or every minute with showSeconds off.

• labels
  Partial<CountdownLabels>

  Every string, English by default (DEFAULT_COUNTDOWN_LABELS): days / hours / minutes / seconds (count, formatted) => "3 days", names { days: (count) => "days" } under the blocks, short { days: "d", ... }, sentence(text, parts) => "3 days and 4 hours left", done "Time's up", and "and", in "in".

• classNames
  Partial<Record<"units" | "unit" | "value" | "label" | "separator" | "done", string>>

  Extra classes for the inner parts: the row, each unit, the tile or digits, the label, the separator, the done content.

• className
  string

  Extra classes for the root, merged last. The root carries data-state (idle, running, done) and data-urgent in the last minute.

Parts

FAQ

Used in

More React data display components