Show Image

To show an image, you need to use the Image element.

Define an Image

You can construct an image by providing the IImageUserConfig object.

import { Image } from "narraleaf-react";

const character1Happy = new Image({
    src: "https://YOUR_IMAGE_URL",
    zoom: 0.5, // The zoom of the image
    position: {
        yalign: 0.3, // The vertical alignment of the image
        xalign: 0.5, // The horizontal alignment of the image
    },
});

This image starts at the center of the screen with a zoom of 0.5. It stays hidden until its show() action runs.

Show the Image

You can show the image by adding actions to the scene.

scene1.action([
    character1Happy.show(),
]);

The image will be displayed on the screen immediately.

Animate its opacity when showing it:

scene1.action([
    character1Happy.show({
        ease: "easeInOut",
        duration: 1000,
    }),
]);

Hide the Image

You can hide the image by adding actions to the scene.

scene1.action([
    character1Happy.hide(),
]);

The image will be hidden from the screen immediately.

The same options work when hiding it:

scene1.action([
    character1Happy.hide({
        ease: "easeInOut",
        duration: 1000,
    }),
]);

Change the Image

Src-based image

You can change the image by updating the image source.

scene1.action([
    character1Happy.char("https://NEW_IMAGE_URL"),
]);

or with a transition.

import {Dissolve} from "narraleaf-react";

scene1.action([
    character1Happy.char("https://NEW_IMAGE_URL", new Dissolve({ duration: 300 })),
]);

Tag-based image

Use tag groups when every appearance is a pre-composited file.

Note: The tag-based image is a feature that allows you to change the image appearance by providing tags.

You can't mix the tag-based image configuration with the normal image configuration.
Normal image configuration has a string as its src property.

import {Image} from "narraleaf-react";

const image = new Image({
    src: {
        groups: [
            ["happy", "sad", "angry"], // group 1
            ["shirt", "jacket", "t-shirt"], // group 2
            ["trousers", "skirt", "shorts"], // group 3
        ],
        defaults: ["happy", "shirt", "trousers"], // default appearance
        resolve: (emotion, top, bottom) => `https://your/image/src/${emotion}_${top}_${bottom}.png`,
    } as const,
});
// The default image will be `https://your/image/src/happy_shirt_trousers.png`

scene1.action([
    image.show(),
    image.char(["angry", "shorts"], new Dissolve({ duration: 1000 })), // change the image to `https://your/image/src/angry_shirt_shorts.png`
]);

If artwork is exported one part per file, use layers. NarraLeaf stacks the parts from bottom to top. Three emotions, three tops, and three bottoms need 9 files instead of 27 pre-composited combinations.

const image = new Image({
    src: {
        // bottom to top
        layers: [
            "body.png",
            {trousers: "trousers.png", skirt: "skirt.png", shorts: "shorts.png"},
            {shirt: "shirt.png", jacket: "jacket.png", tshirt: "t-shirt.png"},
            {happy: "happy.png", sad: "sad.png", angry: "angry.png"},
            {noHat: null, hat: "hat.png"},
            (tags) => tags.has("sad") ? "tears.png" : null,
        ],
        defaults: ["trousers", "shirt", "happy", "noHat"],
    },
});

scene1.action([
    image.show(),
    image.char(["angry", "shorts", "hat"], new Dissolve({ duration: 1000 })),
]);

Each tag changes only its own variant layer. Other active tags stay unchanged. Tags are inferred from the definition, so TypeScript rejects misspellings.

Constant and variant sources are preloaded automatically. A function layer is opaque to the preloader; register every URL it may return:

scene1.preloadImage("tears.png");

See Image for null layers, function layers, wearables, masks, and preload rules.

Animate the Image

You can animate the image with Transform.

import { Transform } from "narraleaf-react";

// Move the image to the right side of the screen
scene1.action([
    character1Happy.transform(
        Transform.create()
            .position("right")
            .commit({ duration: 120, ease: "easeOut" })
    ),
]);

// or

scene1.action([
    character1Happy.transform(Transform.right(120, "easeOut")),
]);

The image moves to the right over 120 milliseconds with an ease-out curve.

Other image transitions

NarraLeaf 0.16 includes the Dissolve, FadeIn, BlurDissolve, Push, Reveal, and ThroughColor engines, plus the Mask pattern vocabulary (wipe, barn door, iris, clock, fan, blinds, dots) that Reveal and ThroughColor animate. All image transitions work with static, tag-based, and layered images.

For more information about the Transform, please check the Transform documentation.