Countdown

"use client"

import * as React from "react"

The Countdown component shows the time left until a deadline. Use it for rate locks, code resends, deposit address lifetimes, approvals and lockouts. It counts down once per second, shows 0:00 muted when the time is up and speaks only at a few milestones, so screen reader users are not interrupted every second. Pick it over Progress when the limit is time rather than an amount.

Installation#

pnpmnpmyarnbun
pnpm dlx shadcn@latest add @dots/countdown
Copy

Usage#

Copyimport { Countdown } from "@/components/ui/countdown"

Copy<Countdown endsAt={rateLockEndsAt} duration={30} variant="ring" label="Rate lock" />

Set the deadline in an effect or from server data, not with Date.now() during render. The component reads the clock only in effects, so the server and the first client render both show a placeholder.

Copyconst [endsAt, setEndsAt] = React.useState<number | null>(null)
 
React.useEffect(() => {
  setEndsAt(Date.now() + 30 * 1000)
}, [])

Features#

• Accepts a Date or a timestamp in milliseconds, and null while loading
• Formats as 0:42, 1:02:05 or 2d 04:13:07
• An optional ring that empties over duration
• Five sizes, from inline text to a hero timer
• A warning tone for deadlines where money can be lost
• onExpire fires once per deadline
• Sparse polite announcements, configurable with announce
• A useCountdown hook for driving the rest of the screen, such as enabling a button

Ring#

Set variant="ring" and pass the whole window as duration in seconds. The ring starts full and empties as time runs out.

"use client"

import * as React from "react"

Sizes#

Use size to switch between inline, sm, default, lg and display. display is for screens that are about the wait itself. Its digits step down for waits of a day or more so they fit a phone column.

"use client"

import * as React from "react"

Inline#

Use size="inline" to keep the surrounding text size. Set spokenLabel={false} when the sentence already names the deadline, and announce="expiry" to speak only when the wait is over.

"use client"

import * as React from "react"

Warning#

Set tone="warning" only where money can be lost after the deadline, such as a deposit address that stops accepting funds. Expiry on its own is not an error.

"use client"

import * as React from "react"

Display#

Combine size="display" with the ring for a lockout or a recovery hold.

"use client"

import * as React from "react"

Several timers#

When a screen shows several long timers, set announce="off" on each. The digits can still be read on demand.

"use client"

import * as React from "react"

Pending and expired#

endsAt={null} shows -:-- while the deadline loads. A deadline in the past shows 0:00 muted with an empty ring.

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

export function CountdownStates() {

Accessibility#

The digits sit in an element with role="timer". They are hidden from screen readers and replaced with words, such as "Rate lock: 24 seconds left", which are read when the user moves to the timer.

• Pass a label that names what runs out. It prefixes the spoken time and every announcement.
• A separate polite region speaks at 5 minutes, 1 minute, every 10 seconds in the last minute, and at expiry. Long deadlines stay quiet until the last 5 minutes.
• Use announce="expiry" for a single wait that unlocks something, and announce="off" when several timers share a screen or the screen announces the outcome itself.
• Keep the countdown mounted through expiry and let it show 0:00. Removing it at zero also removes the "time is up" announcement.
• Color is not the only signal: the expired state also shows 0:00, and tone="warning" should come with text that explains the risk.

API Reference#

Countdown#

Accepts all span props except children.

useCountdown#

Ticks once per second toward a deadline. Reads the clock only in effects, so the first render matches on server and client.

Copyconst { remaining, seconds, expired } = useCountdown(endsAt, onExpire)

formatClock#

Formats whole seconds the way the component shows them: 42 gives "0:42", 3725 gives "1:02:05", two days give "2d 00:00:00".

CopyformatClock(seconds: number): string