ThroughColor

This transition is designed for Image elements.

Cover the frame with a solid colour, hold, then uncover on the next image — so the next image only appears after the colour hold. The images swap behind the fully covered frame, unseen.

The colour covers through any mask pattern. Without a pattern, the colour simply fades in and out: a plain fade to black / white, or a flash with hold: 0. Reveal is the direct A→B counterpart that takes the same patterns.

Usage

import { ThroughColor, Mask } from "narraleaf-react";

// Fade to black, hold, then fade in the next image
image.char("image1.jpg", new ThroughColor({ duration: 1000 }));

// A quick white flash (no hold)
image.char("image1.jpg", new ThroughColor({ duration: 700, color: "#ffffff", hold: 0 }));

// Soft wipe through black
image.char("image1.jpg", new ThroughColor({ duration: 1100, pattern: Mask.wipe({ direction: "left", feather: 15 }) }));

// Classic iris to black: the circle closes rim-in,
// which is the iris pattern's inverted orientation
image.char("image1.jpg", new ThroughColor({ duration: 1400, pattern: Mask.iris(), inverted: true }));

// The clock hand keeps sweeping through the hold instead of backing out
image.char("image1.jpg", new ThroughColor({ duration: 1800, pattern: Mask.clock(), uncover: "continue" }));

Public Methods

constructor

• options: ThroughColorOptions
  • duration: number - The duration of the transition in milliseconds
  • color?: string - The hold colour. Defaults to "#000000".
  • hold?: number - The fraction (0–1) of the duration spent fully covered by the colour. Use 0 for a flash. Defaults to 0.3.
  • pattern?: MaskPattern - The coverage geometry the colour covers the frame through. See Mask. Omit for a plain fade through the colour.
  • inverted?: boolean - Cover through the pattern's inverted (complementary) orientation instead — e.g. Mask.iris() covers centre-out by default, and rim-in (the classic "iris to black") with inverted: true. Defaults to false.
  • uncover?: ThroughColorUncover - How the colour uncovers after the hold; see below. Ignored without a pattern. Defaults to "retreat".
  • easing?: TransformDefinitions.EasingDefinition - The easing function, see TransformDefinitions.EasingDefinition

Uncover Modes

After the hold, uncover picks how the second half plays:

• "retreat" (default) - The cover pattern backs out the way it came: a wipe that entered from the left leaves to the left, a closed iris reopens the way it closed.
• "continue" - The edge keeps travelling in the same direction, so the pattern passes through the frame: a wipe exits out the far side, an iris that closed rim-in reopens centre-out, a clock hand completes a second lap.
• a MaskPattern - The colour uncovers through an unrelated geometry of its own, for an asymmetric cover/uncover — for example, cover with a clock sweep and uncover with a wipe:

image.char("image1.jpg", new ThroughColor({
    duration: 2000,
    pattern: Mask.clock(),
    uncover: Mask.wipe({ direction: "bottom" }),
}));