API reference

Attributes

Attribute	Type	Default	Description
`rate`	time	`1s`	CSS time for one blink cycle
`behavior`	string	`blink`	`blink` \| `pulse` \| `flicker` \| `steps`
`min-opacity`	number	per-mode	Opacity of the "off" phase (0–1)
`count`	number	`infinite`	Number of blinks, then stop
`steps`	number	`2`	Step count for the multi-step engine (min 2)
`step-durations`	list	equal	Per-step hold weights, e.g. `3 1 1` (normalized across the cycle)
`step-by`	string	`element`	`element` \| `letter` \| `word` — step the whole text together, or each unit on its own staggered clock
`pause-on-hover`	boolean	—	Also pauses on `:focus-within`
`play-state`	string	`running`	`running` \| `paused`
`reduced-motion`	string	`respect`	`respect` \| `ignore`
`mode`	string	—	Surface themes: `neon` \| `crt` \| `terminal` \| `warning` \| `alert` \| `police` \| `vegas`. Per-unit motion: `wave` \| `twinkle` \| `sparkle` \| `rainbow` \| `chase` \| `glitch` \| `cascade` \| `typewriter` \| `zoom` \| `flip3d` \| `swing` \| `shake` \| `heartbeat`. Step modes: `extrude` \| `collapse` \| `outline` \| `morph` \| `depth` \| `revolve`. Special: `morse` \| `decode`
`unit`	string	`letter`	`letter` \| `word` — granularity for the motion modes (animate each letter, or each whole word)

Per-unit motion modes split the text into per-unit spans and animate each with a staggered delay. Set unit="word" to animate whole words instead of letters. They honor prefers-reduced-motion.

Methods & properties

Member	Description
`start()`	Play (sets `play-state="running"`)
`stop()`	Pause (sets `play-state="paused"`)
`toggle()`	Flip between running and paused
`refresh()`	Re-render content and recompute after dynamic content changes
`rate`, `behavior`, `minOpacity`, `count`, `steps`, `stepDurations`, `playState`, `mode`, `unit`	Readonly getters reflecting current configuration

Events

Event	Fired when
`blink-start`	The blink starts (on connect and on resume)
`blink-pause`	The blink is paused
`blink-cycle`	Each blink iteration completes

All events bubble.

el.addEventListener('blink-cycle', () => console.log('one blink completed'));

CSS custom properties

Property	Description
`--blink-rate`	Duration of one cycle (also set via the `rate` attribute)
`--blink-min-opacity`	Opacity of the "off" phase
`--blink-stagger`	Per-unit delay step for the letter modes
`--blink-step-ease`	Transition duration between steps (`0s` = hard cut)
`--blink-step-timing`	Transition timing-function between steps (default `ease`)
`--blink-dot`	Morse dot unit, in milliseconds (default 170)
`--blink-bg` / `--blink-fg`	Themed-variant background / foreground

Vanilla Breeze integration

Themed variants read Vanilla Breeze design tokens through layered var() fallbacks. A --blink-* override always wins; absent that, the VB token is used; absent that, a built-in default applies — so non-VB pages render identically.

Mode	Vanilla Breeze tokens consumed
`neon`	`--color-accent`, `--font-sans`
`crt`	`--color-success`, `--color-background`, `--font-mono`
`terminal`	`--color-text`, `--color-surface-sunken`, `--color-accent`, `--font-mono`, `--radius-m`
`warning`	`--color-warning`, `--font-sans`
`alert`	`--color-error`, `--font-sans`
`chase` / `rainbow`	`--color-accent` (the lit unit flashes to it)

See it live on the home page — open the theme picker and switch themes.

Accessibility

prefers-reduced-motion: reduce halts all animation and shows the text fully, unless you set reduced-motion="ignore".
The blink pauses when off-screen and when the tab is hidden.
pause-on-hover also pauses on keyboard focus (:focus-within).
Avoid fast, large-area blinking, which can trigger photosensitive seizures — keep flashes below ~3 Hz and small.