Image

The <Image> primitive embeds an external image (PNG, JPEG, SVG, WebP, or GIF) into your scene. It supports rounded corners, circular/elliptical clipping, and all the standard spatial and animation props.

0.00s / 3.97s · F0

Props

Prop	Type	Default	Description
`src`	`string`	—	Image URL or data URI. Required unless `imageRef` is provided.
`imageRef`	`string`	—	Opaque consumer reference resolved via `ImageResolverProvider` at render time
`x`	`number`	—	Required. X coordinate of the top-left corner
`y`	`number`	—	Required. Y coordinate of the top-left corner
`width`	`number`	—	Required. Rendered width
`height`	`number`	—	Required. Rendered height
`preserveAspectRatio`	`string`	`'xMidYMid meet'`	SVG aspect-ratio keyword
`borderRadius`	`number`	`0`	Corner radius for rounded images
`clipShape`	`'none' \| 'circle' \| 'ellipse'`	`'none'`	Clip the image to a shape
`opacity`	`number`	`1`	Opacity from 0 to 1
`rotation`	`number`	`0`	Rotation in degrees
`rotationOrigin`	`[number, number]`	element center	Center point for rotation
`scale`	`number \| [number, number]`	`1`	Uniform or per-axis scale
`translate`	`[number, number]`	`[0, 0]`	Translation offset `[dx, dy]`
`fadeIn`	`number`	—	Fade in over N frames
`fadeOut`	`number`	—	Fade out over N frames
`zIndex`	`number`	`0`	Rendering order (higher = on top)

Code Examples

import { Player, Image } from '@elucim/core';

<Player width={500} height={300} fps={30} durationInFrames={60}>
  <Image src="/photo.png" x={100} y={50} width={300} height={200} />
</Player>

{
  "width": 500, "height": 300, "fps": 30, "durationInFrames": 60,
  "children": [
    {
      "type": "image", "src": "/photo.png",
      "x": 100, "y": 50, "width": 300, "height": 200
    }
  ]
}

Circular clip

<Image
  src="/avatar.png"
  x={200} y={100} width={100} height={100}
  clipShape="circle"
/>

Rounded corners

<Image
  src="/thumbnail.jpg"
  x={50} y={50} width={400} height={250}
  borderRadius={20}
/>

Rotated image

<Image
  src="/diagram.svg"
  x={100} y={50} width={200} height={200}
  rotation={15}
/>

Image with fade-in animation

<FadeIn duration={30}>
  <Image src="/hero.png" x={0} y={0} width={500} height={300} />
</FadeIn>

Asset References

Instead of hardcoding URLs, you can use opaque asset references via the imageRef prop. At render time, an ImageResolverProvider resolves the reference to a URL.

This is useful when your app manages images through a CMS, asset library, or API — the document stores an ID, and the resolver provides the actual URL at runtime.

import { ImageResolverProvider, Image, Player } from '@elucim/core';

const resolver = (ref) => `https://cdn.example.com/assets/${ref}`;

<ImageResolverProvider resolver={resolver}>
  <Player width={500} height={300} fps={30} durationInFrames={60}>
    <Image imageRef="hero-banner" x={0} y={0} width={500} height={300} />
  </Player>
</ImageResolverProvider>

Resolution rules:

imageRef + resolver → resolved URL
imageRef + no resolver → falls back to src
No imageRef → uses src directly

Async resolvers are also supported — return a Promise<string> for signed URLs or token-gated assets.

See the Image Assets guide for the full workflow including the editor’s image picker.