fluidity-js — Upgrade your UX

Demo & Examples →

⭐ Star this repository if you’d like to support its growth

Quickstart

Choose your weapon:

bun add @jayf0x/fluidity-js
# OR pnpm / aube / yarn / npm ...

Text:

import { FluidText } from '@jayf0x/fluidity-js';

<div style={{ width: '100%', height: 400 }}>
  <FluidText text="Howdy World" fontSize={140} />
</div>;

Image:

import { FluidImage } from '@jayf0x/fluidity-js';

<div style={{ width: '100%', height: '100vh' }}>
  <FluidImage src="/hero.png" algorithm="aurora" />
</div>;

Text + Image:

<div style={{ width: '100%', height: 400 }}>
  <FluidText text="Howdy World" backgroundSrc="/hero.png" />
</div>

---

Programmatic control

Use ref to trigger effects from code — scroll-driven splats, click bursts, attract particles:

import { useRef } from 'react';

import { FluidText } from '@jayf0x/fluidity-js';

export const Interactive = () => {
  const fluid = useRef<FluidHandle>(null);

  return (
    <>
      <div style={{ width: '100%', height: 400 }}>
        <FluidText ref={fluid} text="Splash!" fontSize={120} color="#fff" />
      </div>
      <button onClick={() => fluid.current?.splat(200, 200, 8, -4)}>Splat</button>
      <button onClick={() => fluid.current?.updateConfig({ curl: 0.5 })}>Swirl</button>
      <button onClick={() => fluid.current?.reset()}>Reset</button>
    </>
  );
};

Method	What it does
reset()	Restart the simulation
updateConfig(patch)	Change any config value live
move(x, y, strength?)	Simulate a pointer move
splat(x, y, vx, vy, strength?)	Inject fluid directly — safe to call many times per frame

---

Props

FluidText

Prop	Type	Default
text	string	—
fontSize	number	100
color	string	'#ffffff'
fontFamily	string	'sans-serif'
fontWeight	string | number	900
textBlur	number	1

FluidImage

Prop	Type	Default
src	string	—
imageSize	string | number	'cover'
effect	number	0
obstacleStrength	number	0
refraction	number	1.0
warpStrength	number	0.04

Shared props

Prop	Type	Default
algorithm	FluidAlgorithm	'aurora'
preset	PresetKey	—
pixelRatio	number	1
simResolution	number	0.5
simMaxPixels	number	— (uncapped)
densityDissipation	number	0.83
velocityDissipation	number	0.91
pressureIterations	number	1
curl	number	0
splatRadius	number	0.1
splatForce	number	0.08
specularExp	number	0
shine	number	0
waterColor	FluidColor	'#000000'
glowColor	FluidColor	'#b3d9ff'
backgroundColor	string	'#0a0a0a'
backgroundSrc	string	—
backgroundSize	string | number	'cover'
mouseEnabled	boolean	true
workerEnabled	boolean	true
webGPUEnabled	boolean	true
alphaEnabled	boolean	true
className	string	—
style	CSSProperties	—

---

Algorithms

Value	Vibe
'aurora'	Liquid metal / lava-lamp (default)
'standard'	Colour overlay + gentle refraction
'glass'	Bent-glass distortion, no colour
'ink'	Dense opaque pigment that accumulates and stains
'ripple'	Still water surface with Fresnel rim

<FluidImage src="/photo.jpg" algorithm="aurora" warpStrength={0.3} />
<FluidText text="fluid" algorithm="ripple" />

---

Quality

Control rendering resolution on independent axes — all reactive at runtime.

Prop	Range	Default	What it does
pixelRatio	0.1–1	1	Canvas resolution as fraction of devicePixelRatio. 0.5 on Retina saves ~75% GPU fill.
simResolution	0.1–1	0.5	Simulation FBO size. Lower = cheaper, less detail.
simMaxPixels	>0	— (uncapped)	Hard cap on simWidth × simHeight, applied after simResolution. Both sim axes scale down together (aspect ratio preserved) so ultra-wide or ultra-tall containers stay responsive without a runaway texel count on one axis.

// Ultra-wide hero banner — cap the sim grid regardless of how wide the container gets
<FluidImage src="/banner.jpg" simResolution={1} simMaxPixels={500_000} />

// Sharp canvas, cheap simulation
<FluidImage src="/hero.jpg" pixelRatio={1} simResolution={0.2} />

// Lower canvas res, full simulation quality
<FluidImage src="/hero.jpg" pixelRatio={0.5} simResolution={1} />

---

Simulation props reference

Simulation props that have a physics range accept a normalized 0–1 value — no need to know the raw shader units. Values outside [0, 1] are passed through as raw physics values for advanced overrides.

Prop	Default	Range	Physics range	Description
densityDissipation	0.83	0–1	0.94–1.0	How long ink lingers
velocityDissipation	0.91	0–1	0.9–0.999	How fast fluid slows down
pressureIterations	1	1–50	—	Pressure solve quality vs. cost
curl	0	0–1	—	Swirl intensity
splatRadius	0.1	0–1	0.001–0.04	Brush radius
splatForce	0.08	0–1	0.1–5.0	Force applied by brush
refraction	1.0	0–1	—	Background warp strength
specularExp	0	0–1	0.1–10	Specular highlight sharpness
shine	0	0–1	0–0.15	Highlight intensity
warpStrength	0.04	0–1	0.001–0.1	UV warp intensity (aurora algorithm)
waterColor	#000	—	—	Base fluid colour (hex or [R, G, B] 0–1)
glowColor	#b3d9ff	—	—	Glow / specular colour (hex or [R, G, B] 0–1)

---

Browser support

Works in all modern browsers. Automatically picks the best renderer available — no configuration needed.

Browser	Support
Chrome 113+	✅
Edge 113+	✅
Firefox	✅
Safari 17+	✅
Safari < 17	✅
Mobile Chrome	✅

---

Contributing

See CONTRIBUTING.md for setup and AGENTS.md for code conventions.

---

License

MIT © jayf0x