Number Ticker
<wa-number-ticker>
Number tickers count up or down to a value when they scroll into view and format it with the Intl.NumberFormat API. Use them for dashboard stats, landing page metrics, and running totals.
Screen readers read the final value, but not the numbers in between. For a number that doesn't need to count, use format number instead.
Tickers respect the user's reduced motion preference.
When it's on, the final value shows right away and the ticker still emits the wa-finish event.
Examples
Start & End Values
Use the value attribute to set the number to count to. Tickers count from 0 by default. Set the start-value attribute to start from another number. Start higher than value to count down.
Up:
Down:
Duration & Delay
Use the duration attribute to set the longest a count can take, in milliseconds. A count ends early once the number stops changing. The delay attribute waits before counting from the start value. Later changes to value aren't delayed.
Keep counts under five seconds. A ticker can't be paused, and WCAG asks for a pause control on motion that runs longer.
4 seconds:
1 second, after a 1 second delay:
Easing
Use the easing attribute to change how the count speeds up and slows down. It accepts any CSS easing function, such as linear, ease-in-out, or steps(). The named easings from animation aren't supported. They fall back to the default, like any other invalid value.
default
linear
ease-in-out
steps(10)
Decimal Places
Tickers keep as many decimal places as the value and start-value attributes have, so 99.5 counts in tenths. Use the minimum-fraction-digits or maximum-fraction-digits attribute to set them yourself. Setting one applies to both, so the number of decimal places stays the same during the count. Currency and percent use the locale's usual decimal places instead.
Default:
Always two places:
Currency & Percent
Set the type attribute to currency or percent to change how the number is formatted. Use the currency attribute to set the ISO 4217 currency code, which is USD by default. Percent values are fractions, so 0.87 shows as 87%. For more options, such as currency-display and without-grouping, see format number.
Raised:
Funded:
Localization
Use the lang attribute to set the number formatting locale. Localization is handled by the browser's Intl.NumberFormat API. No language packs are required.
English (US):
German:
English (India):
Arabic (Egypt):
Starting When in View
Tickers wait until they're at least halfway into view before they start counting. A ticker inside a hidden container, such as closed details, starts when it's shown. Use the eager attribute to start counting right away instead. Call the restart() method to play a ticker again.
Open both panels. The first ticker counts as it opens. The second is eager, so it finished while it was closed.
Customizing
Style a ticker with regular CSS. The <wa-number-ticker> element holds the text itself, so color, font-size, and font-weight go right on it. Tickers use tabular figures so digits don't shift as they change.
While a ticker counts, it has the counting custom state, so wa-number-ticker:state(counting) targets it. This example dims each number until it finishes counting.
A ticker inherits the text style around it, so it also works inside a sentence.
Web Awesome runs on coffee. Cups brewed so far:
Formatting the Value
For other formats, set the valueFormatter property to a function that accepts a number and returns a formatted string. The function replaces the formatting attributes and receives unrounded numbers during the count, so round them as needed. The example below uses the Intl.NumberFormat API for compact numbers.
A prefix or suffix doesn't need a formatter. Place the text next to the ticker instead.
Updating the Value
Change the value attribute to count from the number currently shown to the new one. Screen readers announce the new value once it finishes counting.
Score:
Reacting to Completion
The ticker emits the wa-finish event each time it finishes counting. Listen for this event to reveal related content or start another animation.
Stat Cards
Combine a ticker with a card, a badge, and a sparkline to create a stat card that counts up as it scrolls into view.
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/number-ticker/number-ticker.js';
After installing Web Awesome via npm, import this component:
import '@awesome.me/webawesome/dist/components/number-ticker/number-ticker.js';
If you're self-hosting Web Awesome, import this component from your server:
import './webawesome/dist/components/number-ticker/number-ticker.js';
To import this component for React 18 or below, use the following code:
import WaNumberTicker from '@awesome.me/webawesome/dist/react/number-ticker/index.js';
Attributes & Properties
Learn more about attributes and properties.
| Name | Description | Reflects |
|---|---|---|
currencycurrency |
The ISO 4217 currency code to use when formatting.
Type
string
Default
'USD'
|
|
currencyDisplaycurrency-display |
How to display the currency.
Type
'symbol' | 'narrowSymbol' | 'code' | 'name'
Default
'symbol'
|
|
delaydelay |
The number of milliseconds to wait before counting from the start value. Later value changes aren't delayed.
Type
number
Default
0
|
|
durationduration |
The longest a count can take, in milliseconds. A count ends early once the number shown stops changing. Set to
0
to skip the animation.
Type
number
Default
2000
|
|
eagereager |
Starts counting right away instead of waiting until the ticker scrolls into view.
Type
boolean
Default
false
|
|
easingeasing |
The easing function to use for counting. Accepts any CSS easing function, such as
linear, ease-in-out,
cubic-bezier(), steps(), or linear(). Invalid values fall back to the default.
Type
string
Default
'cubic-bezier(0.16, 1, 0.3, 1)'
|
|
maximumFractionDigitsmaximum-fraction-digits |
The maximum number of fraction digits to use. Possible values are 0-100. If only one fraction digit option is set,
it's used for both.
Type
number
|
|
maximumSignificantDigitsmaximum-significant-digits |
The maximum number of significant digits to use. Possible values are 1-21.
Type
number
|
|
minimumFractionDigitsminimum-fraction-digits |
The minimum number of fraction digits to use. Possible values are 0-100. If only one fraction digit option is set,
it's used for both.
Type
number
|
|
minimumIntegerDigitsminimum-integer-digits |
The minimum number of integer digits to use. Possible values are 1-21.
Type
number
|
|
minimumSignificantDigitsminimum-significant-digits |
The minimum number of significant digits to use. Possible values are 1-21.
Type
number
|
|
startValuestart-value |
The number to count from on the first run and when
restart() is called.
Type
number
Default
0
|
|
typetype |
The formatting style to use.
Type
'currency' | 'decimal' | 'percent'
Default
'decimal'
|
|
valuevalue |
The number to count to. Once the ticker has started, changing it counts from the number currently displayed to the
new value.
Type
number
Default
0
|
|
valueFormatter |
A custom formatting function to apply to the number. When set, the formatting properties are ignored. Must be set
with JavaScript. Property only.
Type
(value: number) => string
|
|
withoutGroupingwithout-grouping |
Turns off grouping separators.
Type
boolean
Default
false
|
Methods
Learn more about methods.
| Name | Description | Arguments |
|---|---|---|
restart() |
Plays the ticker again from startValue to value. |
Events
Learn more about events.
| Name | Description |
|---|---|
wa-finish |
Emitted when the ticker finishes counting. |
Custom States
Learn more about custom states.
| Name | Description | CSS selector |
|---|---|---|
counting |
Applied while the number is counting. |
:state(counting)
|
SSR
Learn more about Server-Side Rendering (SSR).
<wa-number-ticker> renders its start value during SSR, but won't start counting until it hydrates on the client and scrolls into view.