Skip to content

API reference

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

@cesarvenzac/rollv1.1.0

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.

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.

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

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

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.

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.

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.

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.

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

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 });