# Roll: Getting started

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

Source: https://cesarvenzac.com/roll/docs/getting-started

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

```typescript
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](https://cesarvenzac.com/roll/docs/rolling) has the rest.

## In React

`Roll` is a `<span>` that rolls to each new `value`. Its other props go on the `<span>`:

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

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

```typescript
// 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](https://cesarvenzac.com/roll/docs/numbers).
- A node, an icon say, which rolls over as one. In React, any element, which should be still: what rolls is a copy.

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

From here: [Looks and effects](https://cesarvenzac.com/roll/docs/looks) for a drum, a cube or a tipping square, and the [Playground](https://cesarvenzac.com/roll#playground) for every option beside the code it takes.

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