# Roll: API reference

> Every function, component and type the package exports, entry by entry: the core, React, the element, Svelte and Vue.

Source: https://cesarvenzac.com/roll/docs/api

Five entries: the core, `@cesarvenzac/roll/react`, `@cesarvenzac/roll/element`, `@cesarvenzac/roll/svelte` and `@cesarvenzac/roll/vue`. Every one takes the same options.

## The core

### roll(element, value, options?)

Makes `element` show `value`, replacing what was in it, and returns a roller. Options given to `set` hold from then on.

```typescript
function roll(
  element: HTMLElement,
  value: Value,
  options?: RollOptions,
): Roller;

type Roller = {
  set(value: Value, options?: RollOptions): void;
  readonly value: Value; // shown, or rolling to
  readonly settled: Promise<void>; // at rest on it
  destroy(): void; // what it shows stays, as text
};
```

### rollGroup(options?)

A group to give rollers as `group`: a change to several staggers across them all, and they settle together.

```typescript
function rollGroup(options?: { onSettle?: () => void }): Group;

type Group = {
  readonly settled: Promise<void>; // every roller at rest
  listen(onSettle: (() => void) | undefined): void;
};
```

### DIGITS, LOWERCASE, UPPERCASE

Reels: `"0123456789"`, a to z and A to Z.

### Options

```typescript
type RollOptions = Options & {
  label?: string; // read aloud: the value's own words
};

type Options = {
  duration?: number; // seconds, the spring's: 0.6
  bounce?: number; // 0 to 1: 0
  stagger?: number; // seconds between characters: 0.03
  staggerFrom?: StaggerFrom; // "start"
  reels?: readonly string[]; // [DIGITS]
  way?: Way | "auto"; // "auto": read from the numbers
  reducedMotion?: boolean; // prefers-reduced-motion
  look?: Look; // "slide"
  direction?: Direction; // "up"
  effects?: readonly Effect[]; // []
  trend?: boolean | { up?: string; down?: string };
  count?: boolean | number; // true: about a second
  format?: (value: number) => string; // String
  tabular?: boolean; // tabular figures: while counting
  onSettle?: () => void;
  group?: Group;
};
```

### Types

```typescript
type Value = string | number | Node;
type Way = "up" | "down";
type StaggerFrom = "start" | "end" | "center";
type Look =
  | "slide" | "drum" | "cube" | "circle" | "square" | "swap";
type Direction = "up" | "down" | "left" | "right";
type Effect = "fade" | "scale" | "blur" | "motion";
```

## React

`@cesarvenzac/roll/react`: client components, React 18 or later.

### <Roll>

A `<span>` showing `value`, rolling to each new one. Its own props go on the `<span>`; it joins the `RollGroup` it's in.

```typescript
type RollProps = Omit<Options, "group"> &
  Omit<HTMLAttributes<HTMLSpanElement>, "children"> & {
    value: string | number | ReactElement;
    label?: string; // an element says nothing without one
  };
```

### <RollGroup>

Groups every `Roll` inside it.

```typescript
function RollGroup(props: {
  children: ReactNode;
  onSettle?: () => void;
}): JSX.Element;
```

## The element

`@cesarvenzac/roll/element` defines `<roll-text>` as it's imported, and exports its class.

### <roll-text>

Its options are attributes: `look`, `direction`, `effects` (`"fade blur"`), `stagger-from`, `trend`, `count` (or its seconds), `tabular`, `duration`, `bounce`, `stagger`, `way`, `reels` (space apart), `reduced-motion` and `label`. Its value is the `value` attribute or property, else its text. Where an attribute and `options` both say, the attribute wins.

```typescript
class RollText extends HTMLElement {
  value: Value; // a number counts with count
  options: RollOptions; // what attributes can't say
  readonly settled: Promise<void>;
}

function optionsOf(element: Element): RollOptions;
```

## Svelte

`@cesarvenzac/roll/svelte`: an action.

```typescript
function roll(node: HTMLElement, params: RollParams): {
  update(params: RollParams): void;
  destroy(): void;
};

type RollParams = RollOptions & { value: Value };
```

## Vue

`@cesarvenzac/roll/vue`: a directive, `v-roll` once registered or imported in `<script setup>`.

```typescript
const vRoll: {
  mounted(element: HTMLElement, binding: Binding): void;
  updated(element: HTMLElement, binding: Binding): void;
  beforeUnmount(element: HTMLElement): void;
};

type Binding = { value: RollBinding };

type RollBinding = Value | (RollOptions & { value: Value });
```

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