Components

Thirteen components. Six wrap the fluid engine; seven are interface primitives on a shared WebGL2 context.

• Fluid: Fluid, FluidBackground, FluidReveal, FluidDistortion, FluidStick, FluidText
• Interface primitives: InkPaper, LiquidButton, LiquidSegmented, LiquidDropZone, LiquidCaustics, LiquidToggle, EnamelText

<Fluid>

The core component. Renders a WebGL fluid simulation on a canvas that fills its parent container.

Input: Mouse, touch and pen drag stroke dye and velocity into the canvas (pointerInput, on by default); mouse and pen hover splat with splatOnHover; pen pressure scales force. Keyboard has no interactive role: the canvas is decorative (aria-hidden) and the content stays fully keyboard-operable.

<script lang="ts">
  import { Fluid } from 'svelte-fluid';
  import type { FluidHandle } from 'svelte-fluid';

  let fluidRef = $state<{ handle: FluidHandle } | undefined>();
</script>

<button onclick={() => fluidRef?.handle.randomSplats(8)}>Splat</button>

<div style="height: 400px">
  <Fluid bind:this={fluidRef} curl={30} bloom shading colorful />
</div>

Accepts all FluidConfig props plus:

Exposes a FluidHandle via bind:this for programmatic control (splats, pause, resume, performance state).

<FluidBackground>

Full-viewport fluid behind page content. Use this as a page or screen wrapper; the canvas stays fixed to the viewport and your content is stacked above it.

Input: Pointer events are read from the window, so mouse, touch and pen movement over the page stirs the fluid while the canvas never intercepts clicks or touch scrolling. Keyboard has no interactive role: the canvas is decorative (aria-hidden) and the content stays fully keyboard-operable.

<script lang="ts">
  import { FluidBackground } from 'svelte-fluid';
</script>

<FluidBackground exclude=".card, .sidebar" splatOnHover colorful shading bloom>
  <!-- your page content -->
</FluidBackground>

DOM elements matching the exclude selector become physical "holes" — the fluid pools around them. The component observes scroll, resize, and DOM mutations to keep exclusion zones accurate.

<script lang="ts">
  import { FluidBackground } from 'svelte-fluid';
</script>

<FluidBackground class="fluid-screen" exclude=".site-nav, .panel" splatOnHover>
  <nav class="site-nav">...</nav>
  <main class="hero-copy">...</main>
  <section class="panel">...</section>
</FluidBackground>

<style>
  :global(.fluid-screen) {
    min-height: 100vh;
    isolation: isolate;
  }

  .site-nav,
  .panel {
    position: relative;
    z-index: 2;
    pointer-events: auto;
  }

  .hero-copy {
    position: relative;
    z-index: 1;
  }
</style>

Defaults to pointerTarget='window' and splatOnHover=true. All FluidConfig props are accepted.

<FluidReveal>

The fluid acts as a reveal mask — cursor movement uncovers content behind a solid cover. Great for scratch-to-reveal effects and interactive hero sections.

Input: Mouse, touch and pen movement over the wrapper uncovers content; touch is forced harder than mouse; the first pointer or touch interaction stops auto-reveal. Keyboard has no interactive role: the canvas is decorative (aria-hidden) and the content stays fully keyboard-operable.

<script lang="ts">
  import { FluidReveal } from 'svelte-fluid';
</script>

<FluidReveal
  sensitivity={0.24}
  coverColor={{ r: 0.15, g: 0.15, b: 0.18 }}
  fringeColor={{ r: 0.6, g: 0.7, b: 0.85 }}
  accentColor={{ r: 0.2, g: 0.35, b: 0.7 }}
>
  <div>Your hidden content here</div>
</FluidReveal>

Also accepts width, height, class, style, lazy, autoPause, fallback, poster, posterAlt, fallbackText, onReady, onError, and all FluidConfig props.

<FluidDistortion>

The fluid velocity field warps an underlying image like liquid glass. Move your cursor to create ripples.

Input: Mouse, touch and pen movement over the wrapper ripples the image; the first pointer or touch interaction stops auto-distortion. Keyboard has no interactive role: the canvas is decorative (aria-hidden) and the content stays fully keyboard-operable.

<script lang="ts">
  import { FluidDistortion } from 'svelte-fluid';
</script>

<FluidDistortion src="/hero.jpg" width={640} height={360} strength={0.4} intensity={24} />

Also accepts width, height, class, style, lazy, autoPause, fallback, poster, posterAlt, fallbackText, onReady, onError, and all FluidConfig props.

<FluidStick>

Dye clings to text or SVG paths. The mask makes dye last longer on the shape, while a small pressure push moves fluid around it.

Input: Mouse, touch and pen drag and hover deposit dye on the canvas; the first pointer activity stops auto-animation. Keyboard has no interactive role: the canvas is decorative (aria-hidden) and the content stays fully keyboard-operable.

<script lang="ts">
  import { FluidStick } from 'svelte-fluid';
</script>

<!-- Text mode -->
<FluidStick text="FLUID" font="900 120px sans-serif" />

<!-- SVG path mode -->
<FluidStick d="M55 5 L25 45 L45 45 L20 95 L75 50 L55 50 L80 5 Z" />

Also accepts width, height, class, style, lazy, autoPause, fallback, poster, posterAlt, fallbackText, onReady, onError, and all FluidConfig props.

<FluidText>

Fluid confined inside text. Wraps <Fluid> with an svgPath container shape in text mode. Automatically measures the text so the font keeps a consistent visual height regardless of length.

Input: Inherits <Fluid> pointer input: mouse, touch and pen drag stroke the fluid inside the letterforms, and hover splats with splatOnHover. The wrapper is role="img" with the text as its label. Keyboard has no interactive role: the canvas is decorative (aria-hidden) and the content stays fully keyboard-operable.

<script lang="ts">
  import { FluidText } from 'svelte-fluid';
</script>

<FluidText
  text="SVELTE"
  height={100}
  seed={42}
  splatOnHover
  shading
  colorful
/>

Also accepts class, style, lazy, autoPause, fallback, poster, posterAlt, fallbackText, onReady, onError, and all FluidConfig props. Defaults to transparent=true.

Interface primitives

Six components for interactive UI rather than backgrounds. Each is a real native element (button, radio group, file input, switch or div) with a decorative WebGL2 surface behind or over it. They share one WebGL2 context per page (ADR-0088/0093), so a dense page does not hit the browser's context cap. Without WebGL2 each renders a plain, fully styled native control that behaves identically. They are not <Fluid> wrappers and take no FluidConfig props.

<InkPaper>

A paper-textured panel that takes watercolour from pointer, touch and pen strokes, for editorial and note-taking surfaces.

<script lang="ts">
  import { InkPaper } from 'svelte-fluid';
</script>

<InkPaper paper="#f4ecdc" pigments={['#2549a8', '#e7b112']} brush={{ size: 28 }} style="height: 260px; padding: 1.5rem">
  <h3 data-ink-resist>Field notes</h3>
  <button data-ink-resist data-ink-wick="0">Keep dry</button>
</InkPaper>

<LiquidButton>

A button for primary actions, with a lit liquid surface that ripples when pressed.

<script lang="ts">
  import { LiquidButton } from 'svelte-fluid';
</script>

<LiquidButton tone="auto" onclick={save}>Save changes</LiquidButton>

<LiquidSegmented>

A single-choice selector (time range, view mode) where the selected option sits on a liquid lens that sloshes across on change.

<script lang="ts">
  import { LiquidSegmented } from 'svelte-fluid';
  let range = $state('week');
</script>

<LiquidSegmented
  name="range"
  legend="Time range"
  options={[
    { value: 'day', label: 'Day' },
    { value: 'week', label: 'Week' },
    { value: 'month', label: 'Month' }
  ]}
  bind:value={range}
/>

<LiquidDropZone>

A file picker that doubles as a drop target, for uploads: the zone raises a meniscus toward the pointer as a file is dragged in.

<script lang="ts">
  import { LiquidDropZone } from 'svelte-fluid';
</script>

<LiquidDropZone
  accept="image/*"
  multiple
  label="Choose images or drop them here"
  onfiles={(files) => upload(files)}
  announce={(files) => files.length + ' images ready'}
/>

<LiquidCaustics>

A wrapper that lays caustic light over live content where the user acts, for emphasis on cards and callouts.

<script lang="ts">
  import { LiquidCaustics } from 'svelte-fluid';
</script>

<LiquidCaustics tone="dark" intensity={0.75} style="padding: 1.5rem; background: #14181f; color: #e8ecf4">
  <h3>Tide tables</h3>
  <p>Move the pointer or tab into the block.</p>
</LiquidCaustics>

<LiquidToggle>

A native checkbox switch for settings. Its shallow liquid lens slides between Off and On, releasing a brief wake through the existing height-field surface. Space, label activation, form submission and reset remain native. Supply a visible children label (recommended) or an explicit aria-label; no generic accessible name is supplied.

<script lang="ts">
  import { LiquidToggle } from 'svelte-fluid';
  let notifications = $state(false);
</script>

<LiquidToggle bind:checked={notifications} onchange={(on) => save(on)}>Notifications</LiquidToggle>

<EnamelText>

A display heading in glazed enamel: molded, rounded relief that gives under a press and relaxes. Use it for one short headline, not body copy. Place it inside your own heading element; the heading supplies the role and size.

<script lang="ts">
  import { EnamelText } from 'svelte-fluid';
</script>

<h2 style="font-size: 4rem; color: #d9462b">
  <EnamelText text="Harbour" />
</h2>