# Roll

> Text that rolls as it changes: digits turn like an odometer's and keep their places, letters and icons roll over.

Source: https://cesarvenzac.com/roll

Package: [@cesarvenzac/roll](https://www.npmjs.com/package/@cesarvenzac/roll) 1.1.0 on npm, MIT licence. Source code: https://github.com/cesarvenzac/roll

```sh
npm install @cesarvenzac/roll
```

*Live example on the page: Every kind. A price, a count, a clock, a word, an icon and a day, each rolling to its next value, the day letter by letter. Pick a look, a direction and effects; Slow stretches the springs to watch a turn.* Its source:

```tsx
// Give Roll each value as it's to be read; it works out the rest.
// A digit keeps its place and turns the way the number went;
// anything else rolls over, an icon as one.
import { Roll } from "@cesarvenzac/roll/react";
import { Check, Copy } from "lucide-react";

<Roll value={yearly ? "€6.67" : "€8"} />
<Roll value={count.toLocaleString("en")} />
<Roll value={clock} /> // "9:59", then "10:00"
<Roll value={saved ? "Saved" : "Saving"} />
<Roll
  value={copied ? <Check /> : <Copy />}
  label={copied ? "Copied" : "Copy"}
/>
// Letters turn through the alphabet, as a split-flap board's:
<Roll value={day} reels={[UPPERCASE, LOWERCASE]} />
// On a drum, a cube, a rolling circle, a tipping square, or in place,
// faded, scaled or blurred as it goes:
<Roll value={price} look="drum" direction="right" />
<Roll value={price} look="swap" effects={["scale", "blur"]} />
```

Roll draws text that rolls as it changes. Give it the value as you'd write it, formatted however you like, and it works out the rest: a number's digits keep their places and turn as an odometer's do, forward as it counts up and back as it counts down; signs, letters and icons roll over. At rest it's plain text.

## Use

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

<Roll value={price} />; // "€8", then "€6.67"
```

Or without React:

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

const price = roll(element, "€8");
price.set("€6.67");
```

## Playground

*Live example on the page: Playground. Every option, beside the code that makes what's shown. Type a value, or let it step through its kind.*

## What it does

- **Digits keep their places.** The units stay the units: 9 becoming 10 turns the 9 to 0 as a 1 rolls in on its left, 9:59 becoming 10:00 keeps its colon, and a fraction is read from its mark.
- **The way the number went.** Each digit turns forward as it counts up and back as it counts down, never the long way round, read from the numbers themselves, signs and fractions included.
- **Everything else rolls over.** Signs, a word's letters in their places, icons as one; with `reels`, letters turn through the alphabet, all one way, as a split-flap board's.
- **Any look, any way.** A flat strip by default; with `look`, a slot machine's drum or a turning cube in perspective, a circle rolling like a wheel, a square tipping over its edge or a swap in place; with `direction`, up, down, left or right; and with `effects`, faded, scaled or blurred as it goes.
- **Counts, tints, tells.** With `count` a number passes every value on its way, with `trend` it flashes green going up and red going down, and `settled`, `onSettle` and groups say when it's landed.
- **Anywhere.** React's `<Roll>`, `roll()` for any element, `<roll-text>` for any page, a Svelte action and a Vue directive, none of which needs anything else installed.
- **Springs that carry on.** Sent somewhere else mid-way, a digit goes on from where it is at the speed it has, and comes home as quickly as a fresh turn.
- **Plain text at rest.** One text node, as crisp as any text, its width the font's, read once by assistive tech; under reduced motion a change fades in where it stands.
- **Small and plain.** TypeScript with no dependencies, about 5 kB, every roller on a page changing in one batch with one layout.

## Docs

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