Shaped Mask Reveal

The first argument (target) is the container element (or a CSS selector string) that gets covered by the mask. Everything else is configured through the options object. Here's what each option does:

Shape geometry (the moving edge of the mask)

• shape — Picks the silhouette of the sweeping edge: "wave" (undulating sine curve), "lines" (jagged straight segments), "zigzag" (sharp triangular teeth), "steps" (staircase pattern), "arc" (a single smooth hump), "sawtooth" (sharp asymmetric teeth), or "diagonal" (a plain slanted straight line).
• direction — Which way the crest travels: "up", "down", "left", or "right". The mask covers the region the crest hasn't swept over yet, so "up" means the reveal moves upward (covering what's above the crest), "right" means it sweeps rightward, etc. Vertical directions use the width as the crest span; horizontal directions use the height.
• amplitude (wave only) — Peak height of the wave's bumps in pixels. Note: the edge always flattens to a straight line at the very start and end of the animation — the amplitude peaks in the middle — so the final state looks clean.
• step (wave only) — How far apart (in px) the wave is sampled along its length. Smaller values = smoother, denser curve; larger values = chunkier, more angular polyline.
• phase — How far the wave pattern "travels" during the reveal, in phase units. The code animates phase linearly alongside the sweep, which makes the ripples slide and undulate across the crest as it moves. Higher values = more visible rippling motion.
• lineCount (lines only) — How many straight segments the jagged edge is divided into.
• lineHeight (lines only) — Maximum vertical jitter of each segment endpoint. Each junction gets a pseudo-random offset between -lineHeight and +lineHeight.
• zigzagCount (zigzag only) — Number of teeth (peaks + valleys) along the edge.
• zigzagHeight (zigzag only) — Tooth height: points alternate between -zigzagHeight and +zigzagHeight.
• stepCount (steps only) — Number of treads in the staircase. Each step is drawn as a horizontal tread plus a vertical riser, so the edge stays axis-aligned.
• stepHeight (steps only) — Maximum height variation between steps. Each step's height is a pseudo-random value (quantized to thirds) scaled by this.
• arcHeight (arc only) — Height of the hump. The edge is a half-sine curve peaking at this height in the middle of the span.
• sawCount (sawtooth only) — Number of saw teeth.
• sawHeight (sawtooth only) — Tooth height; each tooth drops from +sawHeight to -sawHeight and snaps back up.
• tilt (diagonal only) — The total vertical spread of the slanted edge. One end sits at +tilt/2, the other at -tilt/2, producing a diagonal line across the crest span.

Overlay & sizing

• coverColor — The fill color of the mask overlay that hides the content until it's revealed.
• width / height — Fallback dimensions (px) used to build the SVG viewBox only if the container can't be measured (e.g., it's hidden or has zero size). If the container has real dimensions, those are used instead, and a ResizeObserver keeps the mask sized correctly on resize.

Motion

• duration — Total reveal time in seconds.
• ease — GSAP easing function applied to the sweep progress (e.g., "power2.inOut" makes the crest accelerate then decelerate). The wave's phase movement always runs linearly regardless of this.

Triggering

• trigger — How the reveal starts:
  • "click" — clicking (or pressing Enter/Space) on the container plays it.
  • "viewport" — plays automatically when the container scrolls into view (uses GSAP ScrollTrigger if available, falls back to IntersectionObserver, and falls back to an immediate reveal if neither exists).
  • "manual" — nothing fires automatically; you control it via reveal(), reset(), or setProgress().
• autoReveal — If true, plays once immediately on initialization. This applies to "click" and "manual" modes (for "viewport" the scroll trigger handles playback instead).
• scrollStart (viewport mode, ScrollTrigger only) — The ScrollTrigger start position, e.g., "top 50%" means "start when the element's top edge reaches 50% of the viewport height." Ignored by the IntersectionObserver fallback (which uses a fixed 25% visibility threshold).
• replayOnEnter (viewport mode) — If false, the reveal plays once and stays revealed. If true, leaving the viewport resets the mask (covered again) and re-entering replays it — a looping scroll effect.

Intro effect (content inside the container)

• intro — Whether the container's children get a synchronized scale + blur animation while the mask sweeps (they start zoomed/blurred and settle into place as they're uncovered). When enabled, the container also gets overflow: hidden so the scaled content doesn't spill outside.
• introScale — The starting scale factor of the content (e.g., 1.3 = content starts 30% zoomed in and shrinks to 1).
• introBlur — Starting blur radius in px (content starts blurred by this amount and sharpens to 0).

Accessibility

• reducedMotion — Controls respect for the user's motion preferences:
  • "auto" — if the OS/browser reports prefers-reduced-motion: reduce, skip all animation: the mask snaps to fully revealed instantly.
  • "always" — force that instant behavior regardless of the system setting.
  • "never" — always animate, even if reduced motion is requested.
• clickable (click mode only) — If true, makes the container an interactive replay control: pointer cursor, tabindex="0", role="button", keyboard (Enter/Space) handling, and focus outline. If false, no listeners or ARIA attributes are added (so trigger: "click" effectively does nothing without this).
• ariaLabel — The accessible label applied to the container when it's made interactive (only if the element doesn't already have an aria-label).

Callbacks

• onReveal — Function called the moment a reveal starts (after the state resets but before the tween runs). It receives the API object as its argument, so you can chain off it.
• onComplete — Function called when the reveal finishes — either when the GSAP timeline completes or, in reduced-motion mode, immediately after the instant reveal.

Quick notes on the defaults

With the default/example values (shape: "wave", direction: "up", trigger: "viewport"), the container is covered in near-black (#0e1017), and when it scrolls to the middle of the viewport, a rippling wave edge sweeps upward over 1.6 seconds while the underlying content zooms down from 1.3× and un-blurs from 12px into place. The returned object also exposes the methods commented at the bottom — reveal(), reset(), setProgress(t) (0 = fully hidden, 1 = fully revealed, useful for scroll-scrubbing), and destroy() (removes the overlay, listeners, and observers, restoring the element's original attributes and inline styles).