Particle Loader

A canvas dot-matrix loader that shimmers, forms text, a scene, or an orb, then dissolves and loops.

Sketching the scene

Installation

1
Install the component:
npx shadcn@latest add https://ui.amines.fun/r/particle-loader.json

Usage:

jsx

app/page.jsx

1<ParticleLoader variant="text" text="loading..." label="Preparing your result" progress="auto" />

Props

Prop	Type	Default	Description
variant	"text" \| "scene" \| "orb"	"text"	Target shape formed by the particle grid: text, a drawn or image scene, or a rotating orb.
text	string \| string[]	"generating..."	Word or words the dots form in text mode. An array cycles its entries each loop.
scene	((ctx: CanvasRenderingContext2D, width: number, height: number, options: { colors: string[]; cell: number }) => void) \| string \| Array<((ctx: CanvasRenderingContext2D, width: number, height: number, options: { colors: string[]; cell: number }) => void) \| string>	undefined (uses the built-in scene in scene mode)	Scene-mode target as a canvas drawing function, image URL, or array of targets to cycle through. Images need CORS headers to be read by canvas.
cols	number	variant-specific: 72 for text, 48 for scene, 31 for orb	Number of particle columns in the grid. Higher resolution uses more canvas work.
rows	number	variant-specific: 24 for text, 32 for scene, 31 for orb	Number of particle rows in the grid. Higher resolution uses more canvas work.
colors	string[]	["#a23b6c", "#e0505a", "#ef7d3d", "#f7b23c"]	Palette of CSS colors flowing across particles from darker to brighter.
baseColor	string	"#ffffff"	CSS color for idle dots before the target shape forms.
baseOpacity	number	0.1	Opacity of the idle grid dots, from 0 to 1.
hoverColor	string	undefined (lightened from the last palette color)	CSS color used for dots near the pointer.
dotSize	[number, number]	[0.12, 0.8]	Minimum and maximum particle radius as fractions of the grid cell pitch.
shape	"circle" \| "square" \| "diamond"	"circle"	Shape drawn for each particle.
glow	number	0.5	Strength of the halo around larger dots, from 0 to 1.
speed	number	1	Multiplier for the loader's animation clock.
morphSpeed	number	1	Speed multiplier for particles settling into their target shape.
shimmerTime	number	2.6	Seconds each loop spends shimmering before forming the target.
holdTime	number	4	Seconds to hold the formed target. Infinity keeps the shape from dissolving and looping.
paused	boolean	false	Freeze animation time while keeping pointer interaction active.
hover	boolean	true	Enable the pointer reaction that pushes and enlarges nearby dots.
hoverRadius	number	5	Pointer influence radius in grid cells.
hoverStrength	number	1.1	Maximum distance nearby dots are pushed, in grid cells.
hoverBoost	number	0.55	Additional dot size from pointer proximity.
hoverSpring	{ stiffness: number; damping: number }	{ stiffness: 140, damping: 20 }	Framer Motion spring options for the pointer reaction fade.
ripple	boolean	true	Send a shockwave through the grid on pointer down.
fontFamily	string	"ui-sans-serif, system-ui, sans-serif"	CSS font family used to rasterize text targets.
fontWeight	number	800	Font weight used to rasterize text targets.
label	string \| string[] \| null	"Generating" (text), ["Creating image", "Sketching it out", "Adding details"] (scene), or ["Thinking", "Connecting the dots"] (orb); null hides it	Caption above the grid. Arrays cycle through labels every labelInterval milliseconds.
labelInterval	number	2800	Milliseconds between caption changes when label contains multiple entries.
progress	number \| "auto"	undefined (no progress pill)	Show a percentage pill. A number sets a value from 0 to 100; auto animates a repeating progress cycle.
ariaLabel	string	"Loading"	Accessible label on the loader's status region.
className	string	"rounded-2xl bg-black p-5 text-neutral-300"	Additional Tailwind classes appended to the root's built-in layout and the default styling.
labelClassName	string	"mb-4 text-sm font-medium text-neutral-300"	Tailwind classes replacing the default caption styling.
pillClassName	string	"absolute bottom-2 right-2 rounded-full bg-white/10 px-3 py-1.5 text-sm font-medium tabular-nums text-sky-400 backdrop-blur-md"	Tailwind classes replacing the default progress pill styling.
...rest	React.HTMLAttributes<HTMLDivElement>	undefined	Other native div attributes such as id, data-*, and additional accessibility attributes, spread onto the status root.