Getting started
Install Roll and give it a value to show: in React, in any page, as an element, in Svelte or in Vue.
npm install @cesarvenzac/rollPlain TypeScript, published as ES modules with their types, and no dependencies. React is an optional peer, for the React entry alone; the element, the Svelte action and the Vue directive import nothing from their frameworks.
A first roller
roll makes an element show a value, and roll to the next one each time it's told:
import { roll } from "@cesarvenzac/roll";
const price = roll(document.querySelector(".price")!, "€8");
price.set("€6.67");Give it the value as it's to be read, formatted however you like: Roll works out which characters are digits, where each digit's place is and which way the number went. How it rolls has the rest.
In React
Roll is a <span> that rolls to each new value. Its other props go on the <span>:
import { Roll } from "@cesarvenzac/roll/react";
<Roll value={price} className="price" />;
<Roll
value={copied ? <Check /> : <Copy />}
label={copied ? "Copied" : "Copy"}
/>;A server draws the value as plain text, and the browser takes it up as it is: nothing moves as the page hydrates. It's a client component, React 18 or later.
Anywhere else
<roll-text> is a custom element, defined as its entry is imported. Its options are attributes, and its value an attribute or a property:
<script type="module">
import "@cesarvenzac/roll/element";
</script>
<roll-text value="€8" look="drum" trend></roll-text>In Svelte, an action; in Vue, a directive. Each takes a value, or the value with any of the options:
// Svelte: <span use:roll={{ value: price, trend: true }}></span>
import { roll } from "@cesarvenzac/roll/svelte";
// Vue: <span v-roll="price"></span>
import { vRoll } from "@cesarvenzac/roll/vue";Give the Vue directive an element of its own, with nothing inside for Vue to keep: Roll draws in it.
Values
A value is one of three things:
- Text, as you'd write it:
"€6.67","9:59","Saved","1 234,5 €". - A number, written by
format(as JavaScript writes it unless said), so a number can count through the values between: Counting. - A node, an icon say, which rolls over as one. In React, any element, which should be still: what rolls is a copy.
<Roll value={1284} format={(n) => n.toLocaleString("en")} />From here: Looks and effects for a drum, a cube or a tipping square, and the Playground for every option beside the code it takes.