Countdown
High-performance countdown component supporting target time/duration modes, pause/resume, warning state, flip animation, server time calibration, and more. Uses requestAnimationFrame for precise timing.
Basic Usage
Set value to a target timestamp or Date object. The component automatically calculates remaining time and counts down.
Duration Mode
When passing milliseconds (less than 978307200000, i.e., 2001-01-01), it is treated as duration mode.
Custom Format & Text
Customize the display format via the format prop. Supports DD, HH, mm, ss, SSS placeholders. Also supports title and suffix.
Flip Animation
Set flip-animation to enable flip-card style. Combine with labels to add labels for each time unit.
Control Countdown
Get the component instance via ref to manually control the countdown lifecycle.
Warning State
Set a warning threshold via warning-threshold. When the countdown enters this range, is-warning class is added for style customization.
Fully Custom
Use the default slot to fully take over rendering. The slot scope exposes the complete current format object and state flags.
Scenario: Flash Sale
Combines flip animation, labels, and warning state to create an urgent e-commerce countdown.
Server Time Calibration
Handles client clock deviations caused by manual adjustments or system delays.
Real-World: Dialog Sync
In complex SPA applications, the same timer task may appear in multiple places (e.g., product detail page and purchase popup). The component ensures through internal time alignment that the time display stays absolutely consistent when dialogs are frequently opened/closed.
Real-World: Flash Sale List
High-performance requestAnimationFrame driven — even in waterfall lists and high-frequency refresh scenarios, it maintains extremely low CPU usage and smooth UI interactions, with each timer running independently.
Use in Nuxt
The Countdown component fully supports SSR rendering in Nuxt 3/4. Components are auto-imported in Nuxt projects.
SSR Notes:
- ✅ Component initial rendering fully supports SSR
- ✅ Time calculation and formatting completed on server
- ✅ Excellent Hydration performance with no first-load jitter
- ✅ Auto-detects client mount and starts timing
- 💡 Recommended to use with
server-time-offsetfor absolute cross-device time consistency
SSR Performance
Countdown uses requestAnimationFrame internally for timing, which only executes on the client and consumes zero server resources. During initial render, remaining values are pre-calculated based on the current server time, ensuring consistent full-pipeline experience.
API
Props
| Prop | Description | Type | Default |
|---|---|---|---|
| value | Target time (Date/timestamp) or duration (ms) | Date | number | — |
| format | Format template or function | string | (ctx) => string | 'HH:mm:ss' |
| auto-start | Whether to auto-start | boolean | true |
| interval | Refresh interval (ms) | number | 1000 |
| precision | Timing precision (ms) | 1000 | 100 | 10 | 1000 |
| title | Title/prefix text | string | — |
| suffix | Suffix text | string | — |
| use-monospace-font | Use monospace font to prevent digit jumping | boolean | true |
| flip-animation | Enable flip animation mode | boolean | false |
| value-style | Countdown digit inline style | CSSProperties | string | — |
| separator | Separator between time units | string | ':' |
| show-days | Show days ('auto' shows when >= 24h) | boolean | 'auto' | 'auto' |
| show-hours | Whether to show hours | boolean | true |
| show-minutes | Whether to show minutes | boolean | true |
| show-seconds | Whether to show seconds | boolean | true |
| show-milliseconds | Whether to show milliseconds | boolean | false |
| labels | Label template for time units | object | — |
| keep-alive-on-finish | Whether to keep at 00:00:00 when finished | boolean | true |
| warning-threshold | Warning threshold (ms) | number | — |
| timezone-offset | Timezone offset (minutes) for multi-device calibration | number | — |
| server-time-offset | Server-local time difference (ms) | number | 0 |
Events
| Event Name | Description | Parameters |
|---|---|---|
| change | Triggered on countdown update | (ctx: CountdownFormatContext) => void |
| finish | Triggered when countdown ends | () => void |
| start | Triggered when countdown starts | () => void |
| pause | Triggered on pause | () => void |
| resume | Triggered on resume | () => void |
| reset | Triggered on reset | () => void |
| warning | Triggered when entering warning range | (ctx: CountdownFormatContext) => void |
| status-change | Triggered on status change | (status: CountdownStatus) => void |
Slots
| Slot Name | Description | Parameters |
|---|---|---|
| default | Fully custom rendering | { current, remaining, formatted, status, isWarning, isFinished } |
| prefix | Prefix placeholder | — |
| suffix | Suffix placeholder | — |
| value | Custom digit display | { text: string } |
| separator | Custom unit separator | — |
| [key]-cell | Custom specific cell (e.g., seconds-cell) | { value: string } |
Methods (via ref)
| Method | Description | Parameters | Return |
|---|---|---|---|
| start | Start timing | — | void |
| pause | Pause timing | — | void |
| resume | Resume timing | — | void |
| reset | Reset timing | — | void |
| getRemain | Get current remaining ms | — | number |
| getStatus | Get current timing status | — | CountdownStatus |
Type Definitions
type CountdownStatus = 'pending' | 'running' | 'paused' | 'finished'
interface CountdownFormatContext {
total: number // Total remaining ms
days: number
hours: number
minutes: number
seconds: number
milliseconds: number
DD: string // Two-digit days
HH: string
mm: string
ss: string
SSS: string
SS: string // First two digits of ms
S: string // First digit of ms
}Theme Variables
The Countdown component supports customizing styles by overriding the following CSS variables. All color variables integrate with the global theme system, automatically supporting dark mode:
| Variable | Description | Default |
|---|---|---|
--yh-countdown-font-size | Digit font size | 24px |
--yh-countdown-value-color | Digit color | var(--yh-text-color-primary) |
--yh-countdown-label-color | Label color | var(--yh-text-color-secondary) |
--yh-countdown-separator-color | Separator color | var(--yh-text-color-placeholder) |
--yh-countdown-warning-color | Warning state color | var(--yh-color-danger) |
--yh-countdown-finished-color | Finished state color | var(--yh-color-success) |
--yh-countdown-bg | Component root background | transparent |
--yh-countdown-block-bg | Flip block background | var(--yh-fill-color-light) |
--yh-countdown-block-shadow | Flip block shadow | var(--yh-shadow-sm) |
--yh-countdown-block-radius | Flip block border radius | var(--yh-radius-md) |
--yh-countdown-block-padding | Flip block padding | 12px 16px |
--yh-countdown-gap | Internal element gap | 8px |
--yh-countdown-font-family | Default font family | var(--yh-font-family) |
--yh-countdown-monospace-font | Monospace font (anti-jitter) | JetBrains Mono, SF Mono... |