Water
An animated water distortion filter with layered ripples, highlights, and caustics.
Customize
Installation
pnpm dlx shadcn@latest add @vivid-layer/waterUsage
Give the parent element an explicit size. Supply a project-owned image URL or
an HTMLImageElement; the shader fills the available width and height.
import { Water } from "@/components/effects/water"
export function WaterExample() {
return (
<div className="h-96 overflow-hidden rounded-xl">
<Water image="/images/your-image.webp" />
</div>
)
}The installable example uses a vivid-layer-hosted image and needs network access after installation. The core component embeds no asset and works with a consumer-owned local image.
API reference
The wrapper adds playback and runtime safeguards while preserving the
complete Paper Water API. See the
Paper Water reference for the full prop
table and accepted ranges.
| Prop | Type | Default | Description |
|---|---|---|---|
image | string | HTMLImageElement | undefined | Optionally supplies the image distorted by the water effect. |
playback | "auto" | "always" | "paused" | "auto" | Controls motion policy. Auto pauses for reduced motion and while the shader is outside the viewport. |
width / height | number | string | "100%" | Sets the canvas CSS dimensions. Size the parent element to establish the visible area. |
maxPixelCount | number | 2073600 | Caps the rendered pixel budget. Override only after measuring the target devices. |
Accessibility
The shader is decorative by default: it is hidden from assistive technology and does not receive pointer events. Do not use motion as the only way to communicate information, and verify the contrast of overlaid content.
playback="auto" honors reduced motion by rendering a stable frame.
Performance
The default maxPixelCount limits rendering to approximately 1080p, and
automatic playback pauses work once the component is more than 200px outside
the viewport. Use appropriately sized source images and avoid many live image
shaders in the same viewport.
Loading and failure behavior
The component keeps its sized container visually empty during server rendering, image loading, and when WebGL2 is unavailable. A failed image request also leaves the container empty; the unprocessed source image is never exposed.
Credits
The rendering engine is Paper Shaders, distributed under the Apache License 2.0. The example image is Scott Webb's Banff landscape, released under CC0. vivid-layer supplies the adapter, playback and loading policies, documentation, and Registry packaging.
