Countdown

Usage

import { Countdown, CountdownSegment } from '@appica/ui-react/countdown'

<Countdown targetDate="2027-01-01T00:00:00Z">
  <CountdownSegment unit="days" /> <span>days</span>
  <CountdownSegment unit="hours" /> <span>hours</span>
  <CountdownSegment unit="minutes" /> <span>minutes</span>
  <CountdownSegment unit="seconds" /> <span>seconds</span>
</Countdown>

Countdown is the timing engine: give it a targetDate (a Date, epoch-ms number, or date string) or a relative duration in seconds, and it ticks down once per second, breaking the remaining time into days / hours / minutes / seconds. Each CountdownSegment reads one of those units from context and renders it as rolling digits — every digit is a 0–9 strip moved with a GPU transform, so changes slide like an odometer without thrashing layout.

It's intentionally headless: the root is just an inline-flex wrapper and the segments add no styling of their own — they inherit the font, size, and color from your markup. There are no built-in labels — you compose "Days/Hours/…" text (and any separators or boxes) yourself, styling everything through className.

Time zones

Countdown has no timeZone prop, and it doesn't need one. The remaining time is target − now, a subtraction of two absolute instants (both UTC epoch-milliseconds under the hood), so the result is a duration — and a duration is the same everywhere. "3 hours left" is 3 hours in every zone at once, so there is nothing for a time zone to change.

Time zones only matter when you decide which instant targetDate is — and you do that when you construct it, before the component sees it. Pass an offset-bearing string or a real Date, and the countdown is identical for every viewer:

<Countdown targetDate="2027-01-01T00:00:00+09:00" /> // midnight in Tokyo, for everyone
<Countdown targetDate="2027-01-01T00:00:00Z" /> // midnight UTC
<Countdown targetDate={new Date(Date.UTC(2027, 0, 1))} /> // also an absolute instant

Examples

Labelled countdown

Wrap each CountdownSegment with your own label and size it however you like. The digits stay aligned because the segment uses tabular figures.

import { Countdown, CountdownSegment } from '@appica/ui-react/countdown'

type Unit = 'days' | 'hours' | 'minutes' | 'seconds'

function Field({ unit, label }: { unit: Unit; label: string }) {
  return (
    <div className="flex flex-col items-center">
      <CountdownSegment unit={unit} className="text-foreground-intense text-4xl font-semibold" />
      <span className="text-foreground-muted mt-1 text-sm">{label}</span>
    </div>
  )
}

export default function CountdownDefault() {
  return (
    <Countdown targetDate="2027-01-01T00:00:00Z" className="gap-6" aria-label="Time until 2027">
      <Field unit="days" label="Days" />
      <Field unit="hours" label="Hours" />
      <Field unit="minutes" label="Minutes" />
      <Field unit="seconds" label="Seconds" />
    </Countdown>
  )
}

Relative duration

Pass duration (seconds from mount) instead of targetDate for timers like a flash sale, and use onComplete to react when it hits zero.

'use client'

import { useState } from 'react'
import { Button } from '@appica/ui-react/button'
import { Countdown, CountdownSegment } from '@appica/ui-react/countdown'

export default function CountdownDuration() {
  const [done, setDone] = useState(false)

  if (done) {
    return (
      <div className="flex flex-col items-center gap-3">
        <p className="text-foreground-intense text-lg font-semibold">Time&apos;s up! 🎉</p>
        <Button variant="outline" size="sm" onClick={() => setDone(false)}>
          Restart
        </Button>
      </div>
    )
  }

  return (
    <Countdown
      duration={20}
      onComplete={() => setDone(true)}
      className="text-foreground-intense gap-1 text-3xl font-semibold"
      aria-label="Offer ends in"
    >
      <CountdownSegment unit="minutes" />
      <span className="text-foreground-muted">:</span>
      <CountdownSegment unit="seconds" />
    </Countdown>
  )
}

Custom styling

Because every part takes a className (merged via tailwind-merge), you can box each segment, add separators, or restyle the digits entirely.

import { Countdown, CountdownSegment } from '@appica/ui-react/countdown'

const box =
  'bg-background-subtle text-foreground-intense rounded-lg border px-3 py-3.5 font-mono text-2xl font-semibold'

export default function CountdownStyled() {
  return (
    <Countdown targetDate="2027-01-01T00:00:00Z" className="gap-2" aria-label="Time remaining">
      <CountdownSegment unit="hours" className={box} />
      <span className="text-foreground-muted self-center text-2xl font-semibold">:</span>
      <CountdownSegment unit="minutes" className={box} />
      <span className="text-foreground-muted self-center text-2xl font-semibold">:</span>
      <CountdownSegment unit="seconds" className={box} />
    </Countdown>
  )
}

Standalone rolling number

CountdownSegment also works on its own — pass a value instead of a unit to animate any number you drive yourself, no timer required.

'use client'

import { useState } from 'react'
import { Button } from '@appica/ui-react/button'
import { CountdownSegment } from '@appica/ui-react/countdown'

export default function CountdownValue() {
  const [value, setValue] = useState(8)

  return (
    <div className="flex items-center gap-5">
      <CountdownSegment value={value} className="text-foreground-intense text-5xl font-semibold" />
      <div className="flex gap-2">
        <Button variant="outline" size="sm" onClick={() => setValue((v) => Math.max(0, v - 1))}>
          -1
        </Button>
        <Button variant="outline" size="sm" onClick={() => setValue((v) => v + 1)}>
          +1
        </Button>
        <Button variant="outline" size="sm" onClick={() => setValue((v) => v + 10)}>
          +10
        </Button>
      </div>
    </div>
  )
}

RTL

Every Appica UI component supports right-to-left layouts out of the box. Set the dir attribute on a container (commonly your <html> element) so CSS logical properties resolve correctly, and wrap your tree in DirectionProvider so direction-aware behavior follows the same direction.

import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}

The segments reorder to follow the resolved direction, while the digits themselves keep rolling vertically — numbers read the same in any direction. For setup details and caveats, see the RTL guide.

API reference

Countdown

The timing engine and headless container. Renders a <div role="timer"> and provides the remaining time to its CountdownSegment children.

Forwards ref, className, aria-*, and any other <div> attributes. Use aria-label to name the timer (e.g. "Offer ends in").

CountdownSegment

Renders one unit as rolling digits. Use it inside a Countdown with unit, or standalone with value.

Forwards ref, className, and any other <span> attributes. The digit rollers honour prefers-reduced-motion (snapping instantly instead of sliding).

Accessibility

• The root renders role="timer"; give it an aria-label describing what it counts down to.
• The animated digits are aria-hidden; each segment also renders an sr-only plain-text value so screen readers announce the number (with your adjacent label text).
• The timer does not announce on every tick by default (no aria-live), avoiding once-a-second spam. Add aria-live="polite" to the root yourself if live updates are appropriate.
• Digit rolling honours prefers-reduced-motion — digits update instantly without the slide.