Options
Options work the same everywhere: as mount() options, React and Vue props, and <mulling-status> attributes.
Every row can be linked to: for example #size. Defaults in code are real values; “unset” means the option has no value until you give one.
| Option | Attribute | Default | Accepted values and what it does |
|---|---|---|---|
type |
type |
'breath' |
A loader name: breath, orbit, tide, blink, coil, murmur, scribble, pond, or one you registered. Shown when no state is set |
state |
state |
unset | thinking, searching, writing, done or error. Overrides type |
states |
loader-thinking, loader-searching, loader-writing |
{ thinking: 'breath', searching: 'murmur', writing: 'tide' } |
A loader name for any working state. Merges key by key |
labels |
label-thinking, label-searching, label-writing, label-done, label-error |
'Thinking', 'Searching', 'Writing', 'Done', 'Something went wrong' |
What screen readers hear in each state. Merges key by key |
announce |
announce |
'polite' |
'polite': changes are spoken through one shared announcer, so loaders never talk over each other. 'off': the loader is its own role="status" element |
size |
size |
20 |
Width and height in pixels: a number above 0, up to 1024. No units (24, not '24px') |
color |
color |
'currentColor' |
Any CSS color, including var(--brand), oklch() and color-mix() |
speed |
speed |
1 |
A speed multiplier above 0: 0.5 is half speed, 2 is double |
label |
label |
'Loading' |
What screen readers hear when no state is set |
label: null |
decorative |
unset | Hides the loader from screen readers when visible text already explains it |
reducedMotion |
reduced-motion |
'auto' |
'auto' follows the system setting; true always shows the calm version; false always animates |
paused |
paused |
false |
true stops the animation where it is |
maxFps |
max-fps |
30 at 32px and smaller; unset above |
Frame-rate cap for canvas loaders: a number above 0. Infinity (attribute none) removes it |
time |
time |
unset | A number of seconds: freezes the loader that far in, for screenshot tests and static previews |
nonce |
nonce |
unset | Nonce for injected <style> tags; see Content Security Policy |
The handle
Section titled “The handle”mount() returns a handle with update(options), refresh() and destroy().
update()changes only what you pass.labelsandstatesmerge key by key; set a key toundefinedto restore its default, orlabels: undefinedto restore them all.refresh()re-reads colors from the page.destroy()removes the loader. Callingupdate()orrefresh()afterwards does nothing.
Invalid values
Section titled “Invalid values”Options are checked every time they’re set, whether they come from JavaScript, props or attributes. A value that can’t work is replaced by the default, and a warning is logged once. The warning says what to write instead, and suggests the nearest match for a mistyped name:
mulling: invalid size "32px": use a number of pixels, like 24. Using 20.mulling: <mulling-status state="Thinking"> is invalid: use thinking, searching, writing, done or error. Did you mean "thinking"? Using no state.mulling: "orbitt" isn't registered. Did you mean "orbit"? Showing "breath".A loader never breaks or goes blank because of a bad value.