mirror of
https://github.com/tabler/tabler.git
synced 2026-10-12 21:27:06 +04:00
150 lines
5.0 KiB
Plaintext
150 lines
5.0 KiB
Plaintext
---
|
|
title: Countup
|
|
summary: A countup animates a number from zero to its final value when it scrolls into view.
|
|
docs-libs: [countup]
|
|
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';
|
|
import TabsPackage from '@components/TabsPackage.astro';
|
|
import { Code } from 'astro:components';
|
|
import { site } from '@shared/lib/site.ts';
|
|
|
|
## 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
|
|
|
|
Install countup.js with npm:
|
|
|
|
<TabsPackage name="countup.js" />
|
|
|
|
Or include it from a CDN:
|
|
|
|
<Code lang="html" code={`<script src="${site.cdnUrl}/dist/libs/countup.js/dist/countUp.umd.js"></script>`} />
|
|
|
|
Tabler reads the library from the `countUp` global, so load the UMD build above before `tabler.js`. If you install with npm and bundle it yourself, assign it first:
|
|
|
|
```js
|
|
import * as countUp from 'countup.js';
|
|
|
|
window.countUp = countUp;
|
|
```
|
|
|
|
For options beyond the ones below, see the [countUp.js website](https://inorganik.github.io/countUp.js/).
|
|
|
|
## 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.
|
|
|
|
```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>
|
|
|
|
## JavaScript
|
|
|
|
Tabler automatically initializes all elements with `data-countup` on page load. This is the code that runs:
|
|
|
|
<CodeDocs name="countup-init" file="core/js/src/countup.ts" />
|
|
|
|
## 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.
|
|
- Tabler does not check `prefers-reduced-motion`, so a countup animates even for users who asked for less motion. Skip the initialization for them:
|
|
|
|
```js
|
|
if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
|
|
document.querySelectorAll('[data-countup]').forEach((el) => el.removeAttribute('data-countup'));
|
|
}
|
|
```
|
|
|
|
Run it before `tabler.js`, so the number simply stays at its final value.
|