Counter
<wa-counter>
Counters count down to a date or up from one, ticking through years, months, days, and smaller units. Use them for launch countdowns, sale timers, and showing how long something has been running.
Always use ISO 8601 date strings.
Ambiguous formats like 03/04/2020 can be read as March 4 or April 3 depending on the user's browser and locale. A valid ISO 8601 date time string parses the same for every client.
Examples
Date
Set the date attribute to an ISO 8601 string to count down to that moment. An invalid date shows zeros.
To count down to a Date object, set the date property with JavaScript instead.
Duration
Set the duration attribute to a number of milliseconds to count down from the moment the counter is added to the page. Use it for a countdown that isn't tied to a moment in time, such as a quiz timer or a session that's about to expire.
Changing the duration starts the countdown over. The date attribute takes precedence when both are set, and the duration is ignored when counting up.
Label
Use the label attribute to name the counter for assistive devices. The label isn't displayed.
Screen readers read the time as a phrase, such as "2 days 3 hours 5 minutes 9 seconds", instead of the separate digits and labels.
Units
Use the largest-unit and smallest-unit attributes to choose which units the counter shows, from years to seconds. The defaults are days and seconds.
Time beyond the largest unit rolls up into it, so two days show as 48 hours when the largest unit is hours. Months and years follow the calendar instead of a fixed number of days.
Units at zero ahead of the first non-zero unit are hidden, so a countdown with less than a day left starts at hours. Clock-style counters keep every unit so the digits hold their place.
Counting Up
Set the direction attribute to up to count up from a past date. A future date shows zeros until it passes.
Leave out the date attribute to count up from when the counter is added to the page.
Format
Set the format attribute to short or narrow for shorter unit labels, such as "hr" or "h". The default is long. Avoid narrow when the counter shows months, since some locales, such as English, label months and minutes both "m".
Unit Labels
Use the years, months, days, hours, minutes, and seconds slots to replace a unit's label. Slotted labels don't change with the value, and screen readers still read the built-in unit names.
Clock Style
Use the delimiter attribute to show text between units, such as :. Add the without-labels attribute to hide the unit labels for a clock-style display.
Size
Counters are sized relative to the current font size. Set font-size on the counter or an ancestor to change its size. A counter stays on one line, so give a large one a size that scales with the viewport to fit small screens.
Localization
Use the lang attribute to set the counter's locale. Localization is handled by the browser's Intl.NumberFormat API. No language packs are required.
Customizing
Counters inherit the surrounding font and color, and their digits use tabular figures so the width holds steady as they tick. Every unit is as wide as the widest label, which spaces the digits evenly. Style a counter with regular CSS, and reach inside it with the unit, value, label, and delimiter parts.
A counter on a colored surface follows the text color there.
Inline
To set a counter inside a sentence, use the unit part to lay each value and label out in a row, and the label part to match the label's size to the text. The narrow format keeps it short.
The sale ends in
Sale Banner
Combine a counter with a card and a call to action to show how long an offer lasts.
Lock in the discount for your first year. The price goes back up when the clock runs out.
Formatting the Value
Use the valueFormatter property to customize how each unit's number is displayed. Set it to a function that accepts the number and its unit and returns a formatted string. By default, numbers are localized and padded to two digits, such as 05. Screen readers always read the unformatted number.
Pausing
Use the paused attribute to pause the counter. Removing it continues from the time shown, so a countdown that was paused ends later than its date.
Give people a way to pause a counter that isn't essential.
A counter keeps changing. When it's decoration instead of a real deadline, the movement can distract. Add a visible pause control.
Finished Content
Use the finished slot to show something else in place of the units when a countdown reaches zero. The slotted content is also shown when the date had already passed. Without it, the counter stays at zero.
Reacting to Completion
The counter emits the wa-finish event when a countdown reaches zero. It isn't emitted when the date had already passed, and a count up never finishes.
Use the finished custom state to style a countdown at zero. Unlike the event, the state also applies when the date had already passed.
Screen readers don't announce a counter as it changes, and that includes the finish. To announce it, update an element with role="status" when the event fires.
API
Importing
If you're using the autoloader or a hosted project, components load on demand — no manual import needed. To cherry-pick a component manually, use one of the following snippets.
Import this component directly from the CDN:
import 'https://ka-f.webawesome.com/[email protected]/components/counter/counter.js';
After installing Web Awesome via npm, import this component:
import '@awesome.me/webawesome/dist/components/counter/counter.js';
If you're self-hosting Web Awesome, import this component from your server:
import './webawesome/dist/components/counter/counter.js';
To import this component for React 18 or below, use the following code:
import WaCounter from '@awesome.me/webawesome/dist/react/counter/index.js';
Slots
Learn more about using slots.
| Name | Description |
|---|---|
days
|
A custom label for days. |
finished
|
Content to show in place of the units when a countdown is at zero, including one whose date had already passed. |
hours
|
A custom label for hours. |
minutes
|
A custom label for minutes. |
months
|
A custom label for months. |
seconds
|
A custom label for seconds. |
years
|
A custom label for years. |
Attributes & Properties
Learn more about attributes and properties.
| Name | Description | Reflects |
|---|---|---|
datedate |
The date to count down to, or up from. When passing a string, it's strongly recommended to use the ISO 8601 format
to ensure timezones are handled correctly. To convert a date to this format in JavaScript, use
date.toISOString().
When omitted, the counter counts down from duration, or up from the moment it starts when direction is up.
Type
Date | string
|
|
delimiterdelimiter |
Text to show between units, such as
:.
Type
string
Default
''
|
|
directiondirection |
The direction to count. Use
down to count down to the date and up to count up from it.
Type
'down' | 'up'
Default
'down'
|
|
durationduration |
The number of milliseconds to count down from, starting when the counter is added to the page. Changing it starts
the countdown over. Ignored when
date is set or direction is up.
Type
number
|
|
formatformat |
The formatting style of the unit labels.
Type
'long' | 'short' | 'narrow'
Default
'long'
|
|
labellabel |
A label that describes the counter to assistive devices.
Type
string
Default
''
|
|
largestUnitlargest-unit |
The largest unit to show. Time beyond it rolls up into it, so two days show as 48 hours when this is
hours. Units
at zero ahead of the first non-zero unit are hidden unless without-labels is set. Falls back to the default range
when either unit is invalid or the smallest unit is larger than the largest.
Type
CounterUnit
Default
'days'
|
|
pausedpaused |
Pauses the counter. When it's removed, counting continues from the time shown.
Type
boolean
Default
false
|
|
smallestUnitsmallest-unit |
The smallest unit to show. Time below it is dropped. Falls back to the default range when either unit is invalid or
the smallest unit is larger than the largest.
Type
CounterUnit
Default
'seconds'
|
|
valueFormatter |
A custom formatting function to apply to each unit's value. It receives the value and its unit. Screen readers still
read the unformatted value. Must be set with JavaScript. Property only.
Type
(value: number, unit: CounterUnit) => string
|
|
withoutLabelswithout-labels |
Hides the unit labels.
Type
boolean
Default
false
|
|
Events
Learn more about events.
| Name | Description |
|---|---|
wa-finish |
Emitted when a running countdown reaches zero. Not emitted when the date had already passed. |
Custom States
Learn more about custom states.
| Name | Description | CSS selector |
|---|---|---|
finished |
Applied when a countdown is at zero, including one whose date had already passed. |
:state(finished)
|
CSS Parts
Learn more about CSS parts.
| Name | Description | CSS selector |
|---|---|---|
delimiter |
The text shown between units. |
::part(delimiter)
|
label |
Each unit's label. |
::part(label)
|
unit |
The container that wraps each unit's value and label. |
::part(unit)
|
value |
Each unit's value. |
::part(value)
|
SSR
Learn more about Server-Side Rendering (SSR).
<wa-counter> renders zeros during SSR and doesn't start counting until it hydrates on the client, because the server can't know the user's clock.