API reference
Every function, component and type the package exports, entry by entry: the core, React, the element, Svelte and Vue.
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 });