Skip to content

Getting started

Install Roll and give it a value to show: in React, in any page, as an element, in Svelte or in Vue.

@cesarvenzac/rollv1.1.0
npm install @cesarvenzac/roll

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