Every field, in order.

Entry points

Two specifiers. revealed is framework-free; revealed/react is the only thing that touches React and ships its own "use client" banner. A UMD/IIFE build is served by unpkg and jsDelivr as the global revealed.

// Core - no React anywhere in this graph.
import {
  RevealField,
  isSupported,
  presets,
  DEFAULT_EDGE,
  DEFAULT_BRUSH,
  DEFAULT_WAVE,
} from "revealed";
import type {
  RevealOptions,
  ImageSource,
  EdgePreset,
  EdgeOptions,
  BrushOptions,
  WaveOptions,
  SkeletonOptions,
  IdleOptions,
  UvRect,
  ResolvedBrush,
  ResolvedWave,
} from "revealed";

// React.
import { Revealed, useRevealed } from "revealed/react";
import type { RevealedProps, RevealHandle, UseRevealedResult } from "revealed/react";

That is the whole surface. Nothing else is exported.

RevealOptions

The single options object, accepted by the RevealField constructor, by setOptions as a partial, and spread as props on <Revealed />.

React props

<Revealed /> takes everything in RevealOptions plus the five below.

ImageSource

Every image slot - front, back, and the skeleton source - takes either a URL or an object with a narrow-viewport swap.

type ImageSource =
  | string
  | { src: string; small?: string; smallMaxWidth?: number /* default 640 */ };

When small is present the injected plate becomes a real <picture> with a <source media="(max-width: …)">, so the browser picks the file by its own rules and the texture is picked by the same rule. The plate and the texture are never two different images.

EdgeOptions

The shape of the cut between the two plates. Pass an object to edge, or a preset name and then override individual fields by spreading a preset from the presets export.

Edge presets

EdgePreset is the union of these six names. The presets export is the same set as plain objects, so you can build on one:

import { presets } from "revealed";

const sharperInk = { ...presets.ink, feather: 0.006 };

BrushOptions

The stroke the pointer lays into the mask.

WaveOptions

The momentum, passed as brush.wave. The mask’s two spare channels carry a velocity field: a stroke injects into it - forward along the stroke, and rotating in opposite directions on either side of it - and every frame the reveal is dilated along that field while the field itself is transported and damped. No second render target, no extra program, no float textures.

true is the default and false is exactly { enabled: false }. Every field below is a live uniform except resolution, which reallocates the mask.

SkeletonOptions

Passing a bare ImageSource to skeleton is shorthand for { src } with everything below at its default.

IdleOptions

Passing true to idle is shorthand for the defaults; false disables the autopilot.

RevealField

The whole vanilla API. The constructor injects a canvas and the two static plates into host, giving it position: relative if it is currently static.

const field = new RevealField(host, {
  front: "/demo/front.webp",
  back: "/demo/back.webp",
});

new RevealField(host: HTMLElement, options: RevealOptions)

Builds the field. Nothing is drawn until the plates decode; if deferInit is true, GL bring-up waits for an idle callback.

setOptions(next: Partial<RevealOptions>): void

Merges new options in, on the same instance and the same context. A change of image source reloads that plate; a change of the skeleton’s source or mode relinks the display shader; a change of brush.wave.resolution reallocates the mask, at exactly the cost of a resize. Every other field is a uniform and applies on the next frame - including brush.persist, which is why freezing and thawing a reveal costs nothing.

paint(x: number, y: number, strength?: number): void

Lays a stroke at a point in 0..1 uv of the plate, exactly as a pointer would. strength defaults to full.

clear(): void

Wipes the mask back to fully covered - only the front plate is visible. Unconditional: with brush.persist on nothing heals, so this is the only way back.

revealAll(): void

Floods the mask so the back plate is fully visible. It then heals like any other stroke, over brush.trail - so if you want it to stay revealed, pair it with brush.persist. Under brush.spotlight it shows everything for exactly one frame before the next one heals it away.

play(): void

Resumes the render loop. Equivalent to running: true.

pause(): void

Parks the render loop and releases the animation frame. The last frame stays on screen.

readonly progress: number

The last measured 0..1 fraction - the same number handed to onReveal.

readonly supported: boolean

Whether this instance actually brought up hardware WebGL. False means the static plates are what the visitor is looking at.

destroy(): void

Frees textures, framebuffers, programs and buffers, disconnects every observer and listener, and cancels the animation frame. Call it on unmount.

RevealHandle

What a ref on <Revealed /> resolves to: the imperative subset of the field, plus the instance itself.

paint(x, y, strength?) · clear() · revealAll() · play() · pause()

Forwarded straight to the underlying RevealField. Safe to call before the field exists - the calls are simply dropped.

field: RevealField | null

The instance, once it has been constructed - which is null on the server and on the first client render, and non-null from mount onwards. It stays non-null when WebGL is refused: the field still exists, still owns the static plates, and simply reports supported: false.

useRevealed

The same machinery for people who want to own the DOM. Pass a ref to your own host element and the options; you get the field and its live status back.

"use client";

import { useRef } from "react";
import { useRevealed } from "revealed/react";

export function CustomHost() {
  const host = useRef<HTMLDivElement>(null);
  const { field, supported, ready, progress } = useRevealed(host, {
    front: "/demo/front.webp",
    back: "/demo/back.webp",
  });

  return (
    <div ref={host} className="my-own-stage" data-ready={ready}>
      {!supported && <img src="/demo/front.webp" alt="" />}
      <span>{Math.round(progress * 100)}%</span>
      <button type="button" onClick={() => field?.clear()}>Reset</button>
    </div>
  );
}

isSupported

Returns whether this browser will actually run the effect. It is false in exactly three cases: on the server, without a WebGL context backed by real hardware, and under prefers-reduced-motion: reduce. In every one of them a field still renders its static front plate.

import { isSupported } from "revealed";

isSupported(); // false on the server, on software GL, and under reduced motion

The hardware verdict is asked once per page and cached - the throwaway context is created and released on the first call. The reduced-motion half is re-read every time, so a visitor who changes the preference mid-session gets a truthful answer without a reload.