tabler/docs/content/ui/plugins/countup.mdx

---
title: Countup
summary: A countup element is used to display numerical data in an interesting way and make the interface more interactive.
docs-libs: [countup]
description: Animate numbers with the countup component to display statistics dynamically and make dashboards more engaging.
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

Set the `duration` to determine how long the animation should take. By default, the duration is set to 2 seconds, but you can modify it as you wish.

<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

By default the countup will start from zero. If you want to set a different start value use `startVal`.
You can also set the start value to be greater than the final value, so that it counts down instead of up.
To see how the starting value affects the animation, look at the example below.

<Example vertical separated>
<h1 data-countup='{"startVal":12345}'>30000</h1> <h1 data-countup='{"startVal":47655}'>30000</h1>
</Example>

### Decimal places

Set how many decimal numbers should be displayed using `decimalPlaces`. By default, the number of decimal places is set to 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

Disable easing using `"useEasing": false`. Easing is set to `true` by default, so that the animation speed changes over the course of its duration. Easing can be disabled to make the animation linear.

<Example vertical separated>
<h1 data-countup>30000</h1> <h1 data-countup='{"useEasing": false}'>30000</h1>
</Example>

### Use grouping

Disable grouping using `"useGrouping": false`. Grouping is set to `true` by default, so that the number is displayed with a separator.

<Example vertical separated>
<h1 data-countup>30000</h1> <h1 data-countup='{"useGrouping": false}'>30000</h1>
</Example>

### Separator

You can change the default separator using `separator` and specifying the one you wish to use.

<Example vertical separated>
<h1 data-countup>3000000</h1> <h1 data-countup='{"separator":" "}'>3000000</h1>
</Example>

### Decimal separator

You can change the default decimal separator using `decimal` and specifying the one you wish to use.

<Example vertical separated>
<h1 data-countup='{"decimalPlaces":2}'>3.12</h1> <h1 data-countup='{"decimalPlaces":2,"decimal":","}'>3.12</h1>
</Example>

### Prefix

Set the countup prefix using `prefix` and specifying the prefix you want to add, for instance a currency symbol.

<Example vertical separated>
<h1 data-countup='{"prefix":"$"}'>30000</h1> <h1 data-countup='{"prefix":"€"}'>30000</h1>
</Example>

### Suffix

Set the countup suffix using `suffix` and specifying the suffix you want to add, for instance a percentage symbol.

<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.