Skip to content

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.

@cesarvenzac/rollv1.1.0

Counting

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

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

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

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:

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:

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

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