Image

Renders an image file. Layout, padding, and child positioning are inherited from Rect: an Image lays out its children exactly like a Rect does, with a decoded image painted in place of the fill.

0.0s / 4.0s

Usage

import { createScene, Image } from '@motion-script/core';

export default createScene(function* (stage) {
  stage.add(
    <Image
      src="./assets/photo.jpg"
      fit="fill"
      width={800}
      height={450}
      cornerRadius={16}
    />
  );
});

Props

Prop	Type	Default	Description
`src`	`string`	–	Path to the image file
`fit`	`'fill' \| 'fit' \| 'tile' \| 'stretch'`	`'fill'`	How the image fills the node's bounds
`scaling`	`number`	–	Scale multiplier applied to the image before fitting
`transform`	`ImageTransform`	–	Fine-grained image transform (offset, scale, rotation within the bounds)
`filters`	`MediaFilter[] \| FilterChain`	`[]`	Image filters (blur, color adjustments, etc.)
`cornerRadius`	`number \| CornerRadiusProps`	`0`	Corner radius (clips the image)
`cornerStyle`	`'rounded' \| 'angled' \| CornerStyleProps`	`'rounded'`	Corner shape

Fit modes

Value	Behaviour
`'fill'`	Scales the image to cover the bounds, preserving aspect ratio and centering (cropped). The default, Figma-style.
`'fit'`	Scales the image to fit within the bounds, preserving aspect ratio (letterboxed)
`'tile'`	Tiles the image at its natural size (× `scaling`)
`'stretch'`	Stretches each axis independently to exactly fill the bounds, distorting aspect ratio

Animating

Animate standard node props like opacity, scale, cornerRadius, or x/y. For image filters, animate inside a tween:

import { createScene, Image, ImageFilters, createRef, tween, lerpNumber, easeOut } from '@motion-script/core';

export default createScene(function* (stage) {
  const photo = createRef<Image>();

  stage.add(
    <Image
      ref={photo}
      src="./assets/photo.jpg"
      fit="fill"
      width={640}
      height={360}
      cornerRadius={0}
      opacity={0}
    />
  );

  // Fade in
  yield* photo().to({ opacity: 1 }, 0.8, easeOut);

  // Round corners
  yield* photo().to({ cornerRadius: 24 }, 0.6, easeOut);

  // Blur out with a filter
  yield* tween(0.8, (t) => {
    photo().set({ filters: ImageFilters.blur(lerpNumber(0, 20, easeOut(t))) });
  });
});

Notes

Image extends Rect, so it also supports group, gap, align, and padding for laying out children on top of the image.
Placing children inside an Image is useful for overlaying text or icons on top of a photo.
Supported formats depend on the renderer; JPEG, PNG, and WebP are universally supported.
See Image ImageFilters for the full list of available filters.