Countdown widgetPro
A timer on a minute tape you drag to set, or a countdown to a moment in steady tabular digits.
On this page
Installation
Usage
import { CountdownWidget } from "@/components/ui/chatcn/pro/countdown-widget"
<CountdownWidget
title="Focus on the specimen copy"
defaultDuration={25 * 60}
onDone={() => notify("Time to stretch")}
/>
<CountdownWidget
mode="until"
title="Doors open, Porto type night"
target="2026-11-14T19:00:00Z"
remind={remind}
onRemindChange={setRemind}
/>As a timer, the signature is the dial: a minute tape that slides under a fixed needle, like a kitchen timer pulled out flat. Drag it, or focus it and use the arrow keys, to set the length in whole minutes up to max. While it runs the tape moves every frame and the line under the digits says when it ends in your local time. At zero the digits and needle turn amber, the end is announced, and onDone fires once.
defaultStatus and defaultRemaining restore a timer that was already running or paused, for example when the host reloads the widget. +1 min adds a minute in any state.
With mode="until", it counts to target in days, hours, minutes and seconds that change together on the second. onRemindChange adds the reminder toggle; once the moment arrives it says so and shows onJoin as the action. Pass now to freeze the clock for screenshots and tests. Render it inside the card your host draws for a widget answer. It fills the width it is given, so a comfortable max width (around 28 rem) comes from the card, and it follows the host theme through the kit tokens. Pass onExpand where the host can go full screen.
Examples
States
Props
| Prop | Type | Notes |
|---|---|---|
title, meta | ReactNode, ReactNode[] | The header |
mode | "timer" | "until" | Default timer |
duration, defaultDuration, onDurationChange | number | Seconds. Default 25 minutes |
max | number | Longest length on the dial, in minutes. Default 60 |
defaultStatus | "idle" | "running" | "paused" | "done" | Where the timer starts |
defaultRemaining | number | Seconds left when restoring |
onStart, onPause, onReset, onDone | callbacks | Timer events |
target | string | number | Date | For until |
remind, onRemindChange | boolean | The reminder toggle, for until |
onJoin | () => void | The action once the moment arrives |
now | number | A fixed clock in ms |
locale, timeZone | string | For the end time |
loading, error, disabled | boolean | |
onRetry, onExpand | () => void | |
labels | Partial<…Labels> | Every string the widget writes, for translation |
Labels
labels covers the buttons, the dial name and minutes(n), endsAt(time), paused, the hint, the done line and doneAlert(title), the unit names, the reminder, the arrived line and join, remaining(text) for the spoken countdown, and the error copy.
Keyboard
| Key | Action |
|---|---|
| Arrow keys on the dial | One minute less or more |
| Page Up, Page Down | Five minutes more or less |
| Home, End | One minute, or the longest |
| Enter or Space on Start | Start, pause or resume |
Accessibility
- The dial is a slider with its value in minutes; it is disabled while the timer runs.
- The digits are a timer role that does not announce every second; the end is announced once, assertively.
- The countdown reads as one sentence (2 days, 4 hours, 12 min to go) rather than four numbers.
- Done carries a bell icon and words, not only amber.
Motion
The tape moves every frame while the timer runs and follows a drag 1:1, then settles on the nearest minute in 180 ms. Keyboard changes jump. Digits never animate. Reduced motion moves the tape once a second.