# Roll: Counting and knowing when it's done

> Count a number through the values between, tint it as it rises or falls, move several rollers as one, and know when they've landed.

Source: https://cesarvenzac.com/roll/docs/numbers

## Counting

Given a number as a number, `count` walks it through every value between the last and the next, each one rolled:

```tsx
<Roll
  value={visitors}
  count
  format={(n) => n.toLocaleString("en")}
/>
```

It counts on a spring of its own, about a second unless `count` is the seconds to take, and sent somewhere new mid-count it goes on at the speed it has. Text doesn't count: give the number, and `format` to write it.

Each number on the way is rounded as the one it's going to is written before `format` sees it: counting to 1284, `format` gets whole numbers, and to 6.67, hundredths. So 6.67 to 8 drops its decimals at once and lands on 8, 8 to 6.67 shows them at once, and a `toLocaleString` never writes 1,039.233.

While it counts, its digits are tabular figures, every digit one width, so the value holds its width as its digits change every frame. `tabular={false}` keeps the font's own figures.

## Trend

`trend` tints the value a moment as its numbers go up or down, green or red, then lets it fade back to its own colour, as a ticker does. The colours are darkened to read on white; give your own as `{ up, down }`, any CSS colour:

```tsx
<Roll value={price} trend />
<Roll
  value={price}
  trend={{ up: "var(--gain)", down: "var(--loss)" }}
/>
```

A change whose numbers didn't move, a word changing beside them, isn't tinted. The tint is a colour, not a motion, so it shows under reduced motion too.

## Knowing when it's done

A roller's `settled` is a promise that resolves once it's at rest on the value it was last given, its count included, and `onSettle` is called each time it comes to rest:

```typescript
const total = roll(element, "€24", { onSettle: () => save() });

total.set("€31");
await total.settled; // landed
```

## Groups

Rollers in a group move as one. A change to several of them in the same moment staggers across them all, in the page's order, as if they were one value; the group's `settled` waits for every one of them, and its `onSettle` is called each time they've all come to rest:

```typescript
import { roll, rollGroup } from "@cesarvenzac/roll";

const row = rollGroup({ onSettle: () => console.log("landed") });
const price = roll(priceElement, "€8", { group: row });
const total = roll(totalElement, "€24", { group: row });
```

In React, every `Roll` inside a `RollGroup` joins it:

```tsx
import { Roll, RollGroup } from "@cesarvenzac/roll/react";

<RollGroup onSettle={() => setLanded(true)}>
  <Roll value={price} /> <Roll value={total} />
</RollGroup>;
```

## Roll's docs

- [Overview](https://cesarvenzac.com/roll.md): Text that rolls as it changes: digits turn like an odometer's and keep their places, letters and icons roll over.
- [Getting started](https://cesarvenzac.com/roll/docs/getting-started.md): Install Roll and give it a value to show: in React, in any page, as an element, in Svelte or in Vue.
- [How it rolls](https://cesarvenzac.com/roll/docs/rolling.md): Digits that keep their places and turn the way the number went, everything else rolling over, on springs that carry on.
- [Looks and effects](https://cesarvenzac.com/roll/docs/looks.md): A flat strip, a drum, a cube, a rolling circle, a tipping square or a swap in place, in any direction, faded, scaled or blurred as it goes.
- [Counting and knowing when it's done](https://cesarvenzac.com/roll/docs/numbers.md): Count a number through the values between, tint it as it rises or falls, move several rollers as one, and know when they've landed.
- [In the page](https://cesarvenzac.com/roll/docs/page.md): What assistive tech hears, what reduced motion gets, how to style it, how it's drawn on a server, and what it costs.
- [API reference](https://cesarvenzac.com/roll/docs/api.md): Every function, component and type the package exports, entry by entry: the core, React, the element, Svelte and Vue.
