Docs · Package reference

Web component

Use the flickering-dots element anywhere HTML runs.

html

<script type="module">
  import { defineDotsElement } from 'https://cdn.jsdelivr.net/npm/flickering-dots@0.1/element/+esm';
  defineDotsElement();
</script>
<flickering-dots set="ember" state="thinking" size="28"></flickering-dots>

Ember Pulse

With a bundler

import { defineDotsElement } from 'flickering-dots/element';

defineDotsElement();

defineDotsElement registers the flickering-dots element once, so calling it again is safe. Importing flickering-dots/element/define registers it as a side effect instead.

Attributes

set: a preset id such as "ember", or a set as JSON. The Data format works too.
state: the state to play; defaults to thinking, or the first state. Changing it plays the set's transition.
size: width in px, 24 by default; height follows the grid ratio.
on: the lit dot colour; any CSS colour, including variables. Defaults to var(--dot-on).
off: the unlit dot colour; any CSS colour, including variables. Defaults to var(--dot-off).
shape: circle, square, rounded or diamond.
mode: flat, flip or led.
gap: space between dots as a fraction of one dot; defaults to 0.25.
tune: on, off, mode, shape, gap, speed, direction and size as JSON; single attributes win.
label: the accessible label; defaults to the state name. An empty string hides the indicator from assistive tech.

Playback

speed: playback multiplier; 1 is normal speed and 2 plays twice as fast.
direction: forward, reverse or pingpong.
transition: cut, flip or crossfade; overrides the set's transition.
paused: holds the current frame.
frame: shows one frame index with no playback.
cycle: steps through the set's states every 2.4 s.
reduced: forces reduced motion: a still frame (the busiest, or the one the recipe names), or the finished mark for success and error, with no playback.
audible: clicks on frame changes once sound is turned on with setDotSoundEnabled.

paused, cycle, reduced and audible are boolean attributes: present means on, unless the value is "false" or "0".

Rendering without a set

frames: a clip as JSON with frames, durations, cols and rows; overrides set, state and recipe.
recipe: renders a recipe such as "orbit" directly, without a set.
params: recipe parameters as JSON: frames, trail, length, density and seed, plus variant and glyph text for the engine recipes.
cols: grid columns for a recipe, or an override for a set's recipe states.
rows: grid rows for a recipe, or an override for a set's recipe states.

Properties

Attributes mirror the React props, and each one is also a property. Properties take objects too, so set, tune, frames and params can be assigned without JSON. Set state or change the attribute to play the set's transition.

const dots = document.querySelector('flickering-dots');
if (dots) dots.state = 'success';

Errors

When an attribute cannot be used, such as an unknown preset id or JSON that does not parse, the element fires an error event whose detail.message says why, and plays the pulse preset instead.

dots?.addEventListener('error', (event) => {
  if (event instanceof CustomEvent) showProblem(event.detail.message);
});

Sound

Frame clicks are off by default. setDotSoundEnabled turns them on for every indicator with the audible attribute.

import { setDotSoundEnabled } from 'flickering-dots/element';

setDotSoundEnabled(true);