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 scheduling keeps each countdown independent while maintaining smooth UI updates, even in waterfall lists and high-frequency refresh scenarios.
Use in Nuxt
The Countdown component fully supports SSR rendering in Nuxt 3/4. Components are auto-imported in Nuxt projects.
SSR Notes:
- The initial countdown structure and formatted text can be rendered during SSR.
- Remaining time is calculated from the current server render time before hydration.
- The internal animation frame loop starts only on the client after mount.
- Use
server-time-offsetwhen you need stricter server-client time alignment across devices.
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 or duration. | YhCountdownValue | Required |
| format | Format template or custom formatter. | YhCountdownFormat | 'HH:mm:ss' |
| auto-start | Whether the countdown starts immediately. | boolean | true |
| interval | Refresh interval in milliseconds. | number | 1000 |
| precision | Timing precision in milliseconds. | 1000 | 100 | 10 | 1000 |
| title | Prefix text. | string | '' |
| suffix | Suffix text. | string | '' |
| use-monospace-font | Whether a monospace font is used to avoid digit jitter. | boolean | true |
| flip-animation | Whether flip-card animation is enabled. | boolean | false |
| value-style | Inline style applied to the value area. | CSSProperties | string | undefined |
| separator | Separator between time units. | string | ':' |
| show-days | Whether to show days. 'auto' shows days only when needed. | 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 mapping for time units. | Partial<Record<keyof YhCountdownTimeUnits, string>> | undefined |
| keep-alive-on-finish | Whether the zero state stays visible after finish. | boolean | true |
| warning-threshold | Remaining time threshold that triggers warning mode, in milliseconds. | number | undefined |
| timezone-offset | Timezone offset used for time alignment, in minutes. | number | undefined |
| server-time-offset | Difference between server time and local time, in milliseconds. | number | 0 |
| theme-overrides | Component-level theme overrides. | ComponentThemeVars | undefined |
Events
| Event Name | Description | Parameters |
|---|---|---|
| change | Triggered on countdown update | (ctx: YhCountdownFormatContext) => 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: YhCountdownFormatContext) => void |
| status-change | Triggered on status change | (status: YhCountdownStatus) => void |
Slots
| Slot Name | Description | Parameters |
|---|---|---|
| default | Fully custom rendering | { current, remaining, formatted, status, isWarning, isFinished } |
| prefix | Prefix content | - |
| suffix | Suffix content | - |
| value | Custom digit display | { text: string } |
| separator | Custom unit separator | - |
| [key]-cell | Custom specific cell (e.g., seconds-cell) | { value: string } |
Expose
| Method | Description | Parameters | Return |
|---|---|---|---|
| start | Start timing | - | void |
| pause | Pause timing | - | void |
| resume | Resume timing | - | void |
| reset | Reset timing | - | void |
| getRemain | Get current remaining milliseconds | - | number |
| getStatus | Get current countdown status | - | YhCountdownStatus |
Type Definitions
type YhCountdownStatus = 'pending' | 'running' | 'paused' | 'finished'
interface YhCountdownFormatContext {
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... |
Type Exports
| Name | Description |
|---|---|
YhCountdownProps | Props type for YhCountdown |
YhCountdownEmits | Emits type for YhCountdown |
YhCountdownExpose | Expose type for YhCountdown |
YhCountdownTimeUnits | Time units structure type |
YhCountdownFormatContext | Formatting context type |
YhCountdownValue | Countdown target value type |
YhCountdownFormat | Format config type |
YhCountdownStatus | Countdown status union |
YhCountdownInstance | Public instance type for YhCountdown |