# RollingNumber

A built-in tag for an animated counter — the digits **roll to `value`, re-animating each time the
value changes**, the way a live dashboard figure ticks as it updates. It renders inline, so it drops
into a sentence or heading, and the usual `size`, `color`, and `fw` props style it. Give it a `value`
to show; the roll runs over 600 ms by default. On a static page it shows the final value (there's no
value change to animate).

Use it as `{% rollingnumber value='1000' %}` in Markdown, or call it from Python
logic (loops, snippets) via `component('aardvark', 'rollingnumber', …)`.

## A styled stat

A large grape-colored count, grouped with commas by default.



<br>

Source: Markdown

```aardvark
{% rollingnumber value='128000' size='2.5rem' fw='700' color='grape' %}
```


Source: Python

```python
component('aardvark', 'rollingnumber', value='128000', size='2.5rem', fw='700', color='grape')
```



## A faster, linear roll

Shorten `animationDuration` (in milliseconds) and set `timingFunction='linear'` for a steady, quick count.



<br>

Source: Markdown

```aardvark
{% rollingnumber value='99' animationDuration=800 timingFunction='linear' size='xl' fw='700' %}
```


Source: Python

```python
component('aardvark', 'rollingnumber', value='99', animationDuration=800,
          timingFunction='linear', size='xl', fw='700')
```



## A decimal stat

`decimalScale` fixes the number of decimal places — here a `4.9` rating shown to one decimal — and
`animationDuration` lengthens the roll.



<br>

Source: Markdown

```aardvark
{% rollingnumber value='4.9' decimalScale=1 animationDuration=2000 size='xl' fw='700' color='teal' %}
```


Source: Python

```python
component('aardvark', 'rollingnumber', value='4.9', decimalScale=1,
          animationDuration=2000, size='xl', fw='700', color='teal')
```



## Without comma grouping

Comma grouping is on by default. Set `thousandSeparator=false` to count a bare number — useful for
years, IDs, or counts that shouldn't read as a quantity.



<br>

Source: Markdown

```aardvark
{% rollingnumber value='2026' thousandSeparator=false size='xl' fw='700' color='blue' %}
```


Source: Python

```python
component('aardvark', 'rollingnumber', value='2026', thousandSeparator=False,
          size='xl', fw='700', color='blue')
```



## Prefix and suffix

`prefix` and `suffix` wrap the number with fixed text — a currency symbol, a percent sign, a unit —
so the whole figure rolls as one.





<br>

Source: Markdown

```aardvark
{% rollingnumber value='1299' prefix='$' size='xl' fw='700' color='green' %}

{% rollingnumber value='98' suffix='%' size='xl' fw='700' color='blue' %}
```


Source: Python

```python
component('aardvark', 'rollingnumber', value='1299', prefix='$', size='xl', fw='700', color='green')

component('aardvark', 'rollingnumber', value='98', suffix='%', size='xl', fw='700', color='blue')
```



## With other components

Because it renders inline, a rolling stat drops into any other component's body — here as the
headline figure in a [card](/components/data-display/card/) composed in Python.



 developers



<br>

Source: Markdown

```aardvark
{% card title="Active installs" subtitle="And climbing." icon="download" %}
{% rollingnumber value='54213' size='2rem' fw='700' color='indigo' %} developers
{% endCard %}
```


Source: Python

```python
stat = component('aardvark', 'rollingnumber', value='54213', size='2rem', fw='700', color='indigo')
component('aardvark', 'card', title='Active installs', subtitle='And climbing.',
          icon='download', children=stat + ' developers')
```



## Attributes

| Attribute | Valid values | Description |
| --- | --- | --- |
| `value` | string or number | The number to show. Rides as a string and is parsed (`"1234"` and `"12.5"` both work). The roll animates whenever this value changes. |
| `animationDuration` | int (milliseconds) | Roll length (default `600`). A deliberate `0` jumps straight to the value. |
| `timingFunction` | `linear`, `ease` (default), `ease-in`, `ease-out`, `ease-in-out`, or any CSS timing function | The roll's easing curve. |
| `decimalScale` | int | Fixed number of decimal places (defaults to the value's own). |
| `fixedDecimalScale` | bool (default `false`) | Pad with trailing zeros to match `decimalScale`. |
| `thousandSeparator` | bool (default `true`) | Group with commas. Set `false` to disable. |
| `prefix` | string | Fixed text before the number (e.g. `$`). |
| `suffix` | string | Fixed text after the number (e.g. `%`). |
| `size` | a Mantine size token (`xs`–`xl`) or a CSS size (e.g. `2.5rem`) | Font size. |
| `color` | a Mantine color name or hex | Text color. |
| `fw` | a CSS font-weight (e.g. `700`) | Font weight. |
## CSS Selectors

Target the rendered element through its island marker — `[data-aardvark-island="RollingNumber"]` — or through the Mantine Styles API classes (`.mantine-RollingNumber-root` and its inner parts):


```css
/* Every rendered RollingNumber carries this island marker */
[data-aardvark-island="RollingNumber"] { }

/* Mantine Styles API class on the root element */
.mantine-RollingNumber-root { }
.mantine-RollingNumber-digit { }
.mantine-RollingNumber-char { }
```


## Injecting Attributes

`attr={…}` forwards raw HTML attributes — including event handlers — straight onto the rendered element, so you can wire DOM behavior the tag does not expose. The handler can be a full multi-line script, not just one expression — this one logs the value to the console and shows it in an alert:



<br>

Source: Markdown

```aardvark
{% rollingnumber value='128000' size='2.5rem' fw='700' color='grape' attr={'onclick': '''
const value = this.getAttribute('aria-label');
console.log('attr demo value:', value);
alert(value);
'''} %}
```


Source: Python

```python
component('aardvark', 'rollingnumber', value='128000', size='2.5rem', fw='700', color='grape',
          attr={'onclick': '''
const value = this.getAttribute('aria-label');
console.log('attr demo value:', value);
alert(value);
'''})
```