Countdown
A countdown component that refreshes in real time, supports day/hour/minute/second formatting templates, emits oas-finish when reaching zero, and automatically cleans up its timer on disconnect. Set type="countup" to switch to count-up mode (increments from start, no end point).
Basic Usage
Default HH:mm:ss
Days, Hours, Minutes, Seconds
DD:HH:mm:ss template
Chinese Unit Template
Chinese units
Millisecond Precision
Add the SSS token to output milliseconds (zero-padded to 3 digits); internal refresh automatically accelerates to a 50ms granularity. aria-live stays off so high-frequency text changes don't disturb screen readers.
SSS millisecond template
Pause / Resume / Reset
active controls pausing ("false" freezes the frame and stops counting elapsed time; resuming continues from where it stopped); the reset() method restarts from the initial value. Ideal for verification-code resend timers, pomodoro clocks, etc.
active pause/resume + reset()
Count-Up (countup)
type="countup" switches to count-up mode: it increments from start (milliseconds, default 0) with no end point (no oas-finish is emitted), ideal for pomodoro timers, work-time tracking, etc. active pauses/resumes and reset() returns to start, with the same semantics as countdown; format tokens and SSS millisecond precision apply as well; elapsed changes reuse the oas-change event (detail.value is the elapsed milliseconds). In this mode the value attribute is ignored.
Count-up: from 0 + pause/resume + reset()
Prefix / Suffix / Title
The title attribute (or slot="title") renders a heading above; prefix-text / suffix-text flank the display value (attribute text or same-named slots, dual channel; prefix / suffix are compatibility aliases (canonical: prefix-text / suffix-text), usable through both the attribute and property channels (React / Vue bindings included)).
title + prefix / suffix
Finish Callback
oas-finish finished state
Font Size
Font size is fixed at --oas-font-size-lg (16px) by default and does not follow the outer context; override with the CSS variable --oas-countdown-font (e.g. 32px).
API
oas-countdown
Attributes
| Attribute | Description | Type | Default |
|---|---|---|---|
active | Controlled pause: "false" freezes the frame and stops counting elapsed time, resuming continues (absent = running) | string | — |
format | Template: DD/D days, HH/H hours, mm/m minutes, ss/s seconds, SSS milliseconds (50ms internal refresh when SSS present) | string | HH:mm:ss |
prefix-text | Leading text of the display value | — | — |
start | Count-up start offset (milliseconds), only effective with type="countup"; changing it restarts counting | string | 0 |
suffix-text | Trailing text of the display value | — | — |
title | Heading above the display value (native global attribute, absorbed after rendering) | string | — |
type | Timing mode: "countup" counts up from start with no end point (no oas-finish); absent = countdown | string | — |
value | Total countdown duration (milliseconds); ignored in count-up mode | string | 0 |
Events
| Event | Description |
|---|---|
oas-change | Emitted on a throttled basis when the remaining displayed value changes, detail { value: remaining milliseconds }; in count-up mode { value: elapsed milliseconds } |
oas-finish | Emitted once when the countdown reaches zero (not emitted in count-up mode, which has no end point) |
Slots
| Name | Description |
|---|---|
prefix | Leading content (distributed content takes precedence over the prefix attribute text) |
suffix | Trailing content (distributed content takes precedence over the suffix attribute text) |
title | Heading above the value (distributed content takes precedence over the title attribute text) |
CSS Variables
| CSS Variable | Default |
|---|---|
--oas-countdown-font | var(--oas-font-size-lg) |
When the template contains D/DD, hours are counted within the day (0-23); without days, hours roll up into them (e.g. 25:01:01).