Dispersed Text

v1.1.0

FreeWebGLTextBackgroundInteractiveReduced Motion

An advanced interactive typography component where text morphs liquidly on content change and disperses into custom particle fields (flow, explode, attract, wind, gravity, vortex) on interaction. Supports solid or gradient colors, speed-based color mapping, neon glow, custom shapes, and manual animation triggers.

Dispersed Text

Go fullscreen to customize props

Installation

npx vectorvesper add dispersed-text

Run npx vectorvesper init once first to set up your project.

Dependencies

npm install framer-motion

framer-motion

Usage

Import

import { DispersedText } from "@/components/vv/dispersed-text";

Usage

<DispersedText />

Client-only component — disable SSR

This component requires browser APIs and must be rendered client-side only.

import dynamic from "next/dynamic";

const DispersedText = dynamic(
  () => import("@/components/vv/dispersed-text").then((m) => m.DispersedText),
  { ssr: false }
);

This component respects prefers-reduced-motion and provides a graceful fallback.

Props

<DispersedText />

A transparent <canvas> that fills its parent — give the parent a size (e.g. a full-height hero or `absolute inset-0`) and set `color` to contrast with whatever is behind it. Renders the word accessibly via role="img" + aria-label.

Prop	Type	Default	Description
`text*`	`string`	`—`	The word, phrase, or short sentence to form. Particles morph dynamically to new target coordinates when the text changes.
`fontSize`	`number`	`—`	Explicit font size in pixels. If provided, disables dynamic fitWidth width-fitting logic to enforce a constant font height.
`color`	`string`	`"#7EACB5"`	Particle color (any CSS color string). Used as the base color for solid and speed modes.
`gap`	`number`	`6`	Pixel sampling step. Smaller = denser text and more particles (heavier performance).
`fontWeight`	`number \| string`	`700`	Weight used when sampling the text layout.
`fontFamily`	`string`	`system sans stack`	Font stack used when sampling. Web fonts are awaited before sampling to ensure correctness.
`fitWidth`	`number`	`0.82`	Fraction of the canvas width the text block spans (0–1).
`lineHeight`	`number`	`1.15`	Line-height multiplier when text wraps onto multiple lines.
`spring`	`number`	`0.08`	Home-pull spring strength — how fast particles assemble and reform.
`meltSpeed`	`number`	`0.06`	Easing speed of the dispersion/gather transition (per frame, 0–1).
`swirl`	`number`	`1.2`	Vortex force strength applied on cursor interaction.
`swirlRadius`	`number`	`160`	Influence radius in px around the cursor vortex.
`streak`	`number`	`5`	Comet tail length while moving. Set to `0` for round dots.
`dotSize`	`number`	`1.7`	Base dot size or streak thickness in px.
`turbulence`	`number`	`1`	Turbulence noise speed — higher values create busier currents.
`maxDpr`	`number`	`2`	Caps the device pixel ratio for mobile performance optimization.
`debug`	`boolean`	`false`	Paints a live fps + particle-count readout onto the canvas.
`className`	`string`	`""`	Extra classes applied to the canvas element.
`style`	`React.CSSProperties`	`—`	Inline style overrides for the canvas element.
`aria-label`	`string`	`= text`	Accessible image description for screen readers.
`interactionMode`	`"flow" \| "explode" \| "attract" \| "vortex" \| "wind" \| "gravity"`	`"flow"`	The physics model applied when particles disperse.
`colorMode`	`"solid" \| "gradient" \| "speed"`	`"solid"`	Method of coloring particles (solid color, linear gradient, or speed-velocity heatmap).
`gradientColors`	`string[]`	`["#7EACB5", "#E07B9B"]`	List of gradient colors stops (used when colorMode is 'gradient').
`gradientDirection`	`"horizontal" \| "vertical" \| "diagonal"`	`"horizontal"`	Direction of the linear color gradient.
`speedColor`	`string`	`"#FF007A"`	Highlight color that particles morph into at peak velocity (used in speed mode).
`shape`	`"circle" \| "square" \| "triangle" \| "star"`	`"circle"`	Geometric particle shape style.
`glow`	`boolean`	`false`	Enables hardware-accelerated neon drop-shadow glow.
`glowColor`	`string`	`= color`	Color of the neon drop-shadow glow.
`glowBlur`	`number`	`8`	Neon glow blur radius in pixels.
`trigger`	`"hover" \| "click" \| "manual"`	`"hover"`	Interaction trigger that initiates dispersion.
`isDispersed`	`boolean`	`false`	Force dispersion in manual trigger mode.
`progress`	`number`	`0`	Continuous manual control progress (0 to 1) in manual trigger mode.
`windAngle`	`number`	`0`	Angle of wind in radians (0 is right, Math.PI/2 is down) used in wind mode.

Examples

Standard Hero

<DispersedText text="VECTOR" color="#ffffff" />

Neon Glow & Shapes

<DispersedText text="GLOW" shape="star" color="#00FFCC" glow={true} glowBlur={15} />

Linear Gradient

<DispersedText text="SPECTRUM" colorMode="gradient" gradientColors={["#FF007A", "#7928CA", "#00DFD8"]} />

Velocity Heatmap

<DispersedText text="VELOCITY" colorMode="speed" speedColor="#FF007A" />

Gravity Physics

<DispersedText text="BOUNCE" interactionMode="gravity" />

Give the parent a size. The canvas fills its container (width: 100%; height: 100%). Put it inside a sized parent box (like relative h-96 w-full) and set colors to contrast the surface behind.

Respects user system preferences — falls back automatically to drawing a calm, static dot field of the formed text.

Pre-calculates parsed RGB vectors and employs global memoized color tables to optimize drawing speed. Neon glow uses hardware-accelerated CSS GPU filters rather than canvas shadows for zero-overhead rendering.

Source

export { default as DispersedText } from "./DispersedText";
export type { DispersedTextProps } from "./DispersedText";

View on GitHub →Report an issue