Docs · Package reference

Core functions

Framework-free helpers for building, encoding and playing frames.

Build frames

import { build } from 'flickering-dots';

const clip = build('orbit', { cols: 7, rows: 7 }, { trail: 2 });
// clip.frames: one array of 0 and 1 per frame, row by row
// clip.durations: milliseconds, one per frame

build("orbit", 7×7)

Play frames

import { build, createPlayer } from 'flickering-dots';

const clip = build('pulse', { cols: 7, rows: 7 });
const player = createPlayer({
  clip,
  onFrame: (index) => paint(clip.frames[index]),
});

player.play();

createPlayer holds each frame for its duration divided by speed and loops by default; pass loop: false with onEnd to play once. It never touches the DOM, so paint is your own drawing function. pause, seek, setSpeed and stop control playback.

Save and load sets

import { decodeSet, encodeSet } from 'flickering-dots';
import type { IndicatorSet } from 'flickering-dots';

export function saveSet(set: IndicatorSet): string {
  return JSON.stringify(encodeSet(set));
}

export function loadSet(json: string): IndicatorSet {
  return decodeSet(JSON.parse(json));
}

encodeSet resolves every state to frames and returns the plain JSON form described in Data format. decodeSet checks unknown input and throws a readable Error when it is not a valid set.

Import grid arrays

import { parseGridArray } from 'flickering-dots';

const clip = parseGridArray([
  ['000', '010', '000'],
  ['010', '111', '010'],
]);

parseGridArray reads flicker-dot style grid arrays: a list of frames, each a list of rows, each row an array of 0 and 1 or a string of them. Every frame gets 90 ms, and bad input throws a readable Error.

Presets

import { getPreset, PRESETS } from 'flickering-dots';

const names = PRESETS.map((preset) => preset.name);
const ember = getPreset('ember');

PRESETS lists the built-in sets in the Library's Featured order. getPreset returns undefined for an unknown id. Importing either includes every preset in your bundle.