mirror of
https://github.com/tabler/tabler.git
synced 2026-10-12 05:06:55 +04:00
184 lines
7.0 KiB
Plaintext
184 lines
7.0 KiB
Plaintext
---
|
|
title: Countup
|
|
summary: A countup animates a number from zero to its final value when it scrolls into view.
|
|
description: Animate numbers with the countup component, for statistics on dashboards and landing pages.
|
|
related: [/ui/plugins/chart]
|
|
---
|
|
import Example from '@components/Example.astro';
|
|
import CodeDocs from '@components/CodeDocs.astro';
|
|
|
|
## Overview
|
|
|
|
A countup animates a number from a starting value up to its final value. Use it for statistics on a dashboard or a landing page, where the number is the point of the block.
|
|
|
|
Write the final number as the text of the element and add `data-countup`. Tabler finds every such element and animates it when it scrolls into view, so no JavaScript of your own is needed.
|
|
|
|
<Example centered>
|
|
<h1 data-countup>30000</h1>
|
|
</Example>
|
|
|
|
## Installation
|
|
|
|
Countup is part of `tabler.js` and has no dependency, so there is nothing extra to install or load.
|
|
|
|
## Usage
|
|
|
|
Add `data-countup` to any text element and write the target number inside it. The animation starts as soon as the number enters the viewport. `data-tblr-countup` works the same way.
|
|
|
|
```html
|
|
<h1 data-countup>30000</h1>
|
|
```
|
|
|
|
Pass options as JSON in the same attribute. Every option below works this way.
|
|
|
|
```html
|
|
<h1 data-countup='{"duration":4,"suffix":"%"}'>300</h1>
|
|
```
|
|
|
|
### Duration
|
|
|
|
`duration` sets how long the animation takes, in seconds. The default is 2.
|
|
|
|
<Example vertical separated>
|
|
<h1 data-countup>30000</h1> <h1 data-countup='{"duration":4}'>30000</h1> <h1 data-countup='{"duration":6}'>30000</h1>
|
|
</Example>
|
|
|
|
### Starting value
|
|
|
|
`startVal` sets the starting value; the default is zero. A start value above the final one makes the number count down instead of up.
|
|
|
|
<Example vertical separated>
|
|
<h1 data-countup='{"startVal":12345}'>30000</h1> <h1 data-countup='{"startVal":47655}'>30000</h1>
|
|
</Example>
|
|
|
|
### Decimal places
|
|
|
|
`decimalPlaces` sets how many decimals are shown. The default is 0.
|
|
|
|
<Example vertical separated>
|
|
<h1 data-countup>3.123</h1> <h1 data-countup='{"decimalPlaces":1}'>3.123</h1> <h1 data-countup='{"decimalPlaces":2}'>3.123</h1> <h1 data-countup='{"decimalPlaces":3}'>3.123</h1>
|
|
</Example>
|
|
|
|
### Easing
|
|
|
|
Easing is on by default, so the animation slows down towards the end. Set `"useEasing": false` for a linear animation.
|
|
|
|
<Example vertical separated>
|
|
<h1 data-countup>30000</h1> <h1 data-countup='{"useEasing": false}'>30000</h1>
|
|
</Example>
|
|
|
|
### Use grouping
|
|
|
|
Grouping is on by default, so thousands get a separator. Set `"useGrouping": false` to turn it off.
|
|
|
|
<Example vertical separated>
|
|
<h1 data-countup>30000</h1> <h1 data-countup='{"useGrouping": false}'>30000</h1>
|
|
</Example>
|
|
|
|
### Separator
|
|
|
|
`separator` sets the thousands separator.
|
|
|
|
<Example vertical separated>
|
|
<h1 data-countup>3000000</h1> <h1 data-countup='{"separator":" "}'>3000000</h1>
|
|
</Example>
|
|
|
|
### Decimal separator
|
|
|
|
`decimal` sets the decimal separator.
|
|
|
|
<Example vertical separated>
|
|
<h1 data-countup='{"decimalPlaces":2}'>3.12</h1> <h1 data-countup='{"decimalPlaces":2,"decimal":","}'>3.12</h1>
|
|
</Example>
|
|
|
|
### Prefix
|
|
|
|
`prefix` adds text before the number, for example a currency symbol.
|
|
|
|
<Example vertical separated>
|
|
<h1 data-countup='{"prefix":"$"}'>30000</h1> <h1 data-countup='{"prefix":"€"}'>30000</h1>
|
|
</Example>
|
|
|
|
### Suffix
|
|
|
|
`suffix` adds text after the number, for example a percent sign.
|
|
|
|
<Example vertical separated>
|
|
<h1 data-countup='{"suffix":"%"}'>300</h1> <h1 data-countup='{"suffix":"‰"}'>300</h1>
|
|
</Example>
|
|
|
|
### Time
|
|
|
|
Set `"format": "time"` for a value written as hours and minutes. The number counts in minutes and is printed as `h:mm`.
|
|
|
|
<Example vertical separated>
|
|
<h1 data-countup='{"format":"time"}'>3:28</h1> <h1 data-countup='{"format":"time","suffix":" hrs"}'>12:05</h1>
|
|
</Example>
|
|
|
|
## JavaScript
|
|
|
|
Tabler ships a `CountUp` component that works like the Bootstrap components: it is created once per element and stored on it. On page load Tabler creates one for every element with `data-countup`. This is the code that runs:
|
|
|
|
<CodeDocs name="countup-init" file="core/js/src/countup.ts" />
|
|
|
|
Create the component yourself for an element added later. Options go in the `data-countup` attribute, in the config object, or both; the object wins.
|
|
|
|
```js
|
|
const countup = new tabler.CountUp(document.getElementById('total'), { duration: 4 });
|
|
```
|
|
|
|
For any format the options cannot express, pass a `formatter` function. It gets the current number on every frame and returns the text to show:
|
|
|
|
```js
|
|
new tabler.CountUp(document.getElementById('size'), {
|
|
formatter: (value) => `${(value / 1024).toFixed(1)} GB`,
|
|
});
|
|
```
|
|
|
|
By default the animation starts when the element scrolls into view. Set `autoAnimate` to `false` to start it right away, or to control it yourself:
|
|
|
|
```js
|
|
const countup = tabler.CountUp.getOrCreateInstance(element, { autoAnimate: false });
|
|
countup.reset();
|
|
countup.start();
|
|
```
|
|
|
|
| Method | Description |
|
|
| --- | --- |
|
|
| `start()` | Starts the animation. |
|
|
| `reset()` | Sets the number back to the starting value, so the animation can run again. |
|
|
| `update(value)` | Animates to a new final value. |
|
|
| `pauseResume()` | Pauses a running animation, or resumes a paused one. |
|
|
| `dispose()` | Stops the animation and removes the component from the element. |
|
|
| `getInstance(element)` | Static. Returns the component for the element, or `null`. |
|
|
| `getOrCreateInstance(element, config)` | Static. Returns the component for the element and creates it when needed. |
|
|
|
|
`start.bs.countup` fires on the element when an animation begins, and `complete.bs.countup` when the number reaches its final value:
|
|
|
|
```js
|
|
document.getElementById('total').addEventListener('complete.bs.countup', () => {
|
|
console.log('done counting');
|
|
});
|
|
```
|
|
|
|
| Option | Default | Description |
|
|
| --- | --- | --- |
|
|
| `autoAnimate` | `true` | Start when the element scrolls into view. `false` starts at once. |
|
|
| `startVal` | `0` | The number to count from. |
|
|
| `duration` | `2` | Length of the animation, in seconds. |
|
|
| `decimalPlaces` | `0` | Decimals shown. |
|
|
| `useEasing` | `true` | Slow down towards the end. `false` counts at a steady pace. |
|
|
| `useGrouping` | `true` | Put a separator between thousands. |
|
|
| `separator` | `,` | The thousands separator. |
|
|
| `decimal` | `.` | The decimal separator. |
|
|
| `prefix`, `suffix` | none | Text before and after the number. |
|
|
| `format` | `number` | `time` reads and prints the value as `h:mm`, counting in minutes. |
|
|
| `formatter` | none | A function that turns the current number into the text to show. Config object only. |
|
|
|
|
## Accessibility
|
|
|
|
- Write the final number in the HTML, as the examples do. That is what a search engine indexes, what shows without JavaScript, and what a screen reader reads if it reaches the element before the animation starts.
|
|
- Never put a countup inside an `aria-live` region. The text changes on every frame, so a live region would announce dozens of intermediate numbers.
|
|
- The number on its own says nothing. Give it a visible label next to it, or an `aria-label` on the block that holds both.
|
|
- Users who asked for reduced motion get the final number at once: the countup checks `prefers-reduced-motion` and skips the animation for them.
|