---
title: "Image Elements"
canonical_url: https://docs.zvid.io/docs/structure/image-elements/
source: docs/structure/image-elements.md
content_revision: 6338386a1dd87e4a
---

# Image Elements

`IMAGE` elements add remote images to the composition. The API validates the
URL and visual options, then Zvid downloads and checks the asset before rendering.
Use a public direct media URL; see [Media assets](https://docs.zvid.io/docs/concepts/media-assets/)
for uploads, supported sources, and download failures.

## Interface

```typescript
interface ImageItem {
  type: "IMAGE";
  src: string;
  x?: number;
  y?: number;
  width?: number;
  height?: number;
  anchor?: Anchor;
  position?: PositionPreset;
  resize?: "contain" | "cover";
  enterBegin?: number;
  enterEnd?: number;
  exitBegin?: number;
  exitEnd?: number;
  track?: number;
  opacity?: number;
  angle?: number;
  flipV?: boolean;
  flipH?: boolean;
  enterAnimation?: XFadeEffect | null;
  exitAnimation?: XFadeEffect | null;
  filter?: FilterOptions;
  cropParams?: CropParams;
  chromaKey?: ChromaKey;
  radius?: BorderRadius;
  zoom?: boolean | { depth?: number };
}
```

## Required Fields

| Property | Type      | Notes                               |
| -------- | --------- | ----------------------------------- |
| `type`   | `"IMAGE"` | Case-insensitive in API validation. |
| `src`    | `string`  | Remote `http` or `https` URL.       |

## Properties

Placement, timing, layering, and animation fields are shared by all visual
elements — see [Common Element Properties](https://docs.zvid.io/docs/structure/common-properties/). Images
support every media option in the
[support matrix](https://docs.zvid.io/docs/structure/common-properties/#media-only-properties):
[`resize`](https://docs.zvid.io/docs/structure/properties/resize/), [`zoom`](https://docs.zvid.io/docs/structure/properties/zoom/),
[`filter`](https://docs.zvid.io/docs/structure/properties/filter-options/),
[`cropParams`](https://docs.zvid.io/docs/structure/properties/crop-params/),
[`chromaKey`](https://docs.zvid.io/docs/structure/properties/chroma-key/), and
[`radius`](https://docs.zvid.io/docs/structure/properties/border-radius/).

## Examples

The JSON blocks are **visual element fragments** for `payload.visuals` or a
scene's `visuals`. The recorded previews demonstrate the named property with
their own full project fixtures, available alongside each preview. Their
canvas sizes and surrounding composition can differ from the short fragments.

### Simple Image

```json
{
  "type": "IMAGE",
  "src": "https://cdn.pixabay.com/photo/2022/08/16/05/50/straw-bales-7389396_1280.jpg",
  "x": 100,
  "y": 100,
  "width": 400,
  "height": 300
}
```

### Centered Cover Image

```json
{
  "type": "IMAGE",
  "src": "https://cdn.pixabay.com/photo/2024/10/02/18/24/leaf-9091894_1280.jpg",
  "width": 1280,
  "height": 720,
  "position": "center-center",
  "resize": "cover"
}
```


```json
{
  "name": "docs-img-cover",
  "width": 960,
  "height": 540,
  "duration": 4,
  "backgroundColor": "#000000",
  "visuals": [
    {
      "type": "IMAGE",
      "src": "https://cdn.pixabay.com/photo/2024/10/02/18/24/leaf-9091894_1280.jpg",
      "width": 960,
      "height": 540,
      "position": "center-center",
      "resize": "cover"
    }
  ]
}
```

Recorded fixture: resize cover on a 960×540 canvas

[Watch rendered example](https://cdn.zvid.io/library/docs/img-cover.mp4)


### Cropped Image

```json
{
  "type": "IMAGE",
  "src": "https://cdn.pixabay.com/photo/2023/06/04/20/21/cat-8040862_1280.jpg",
  "x": 300,
  "y": 200,
  "width": 400,
  "height": 300,
  "cropParams": {
    "x": 100,
    "y": 50,
    "width": 800,
    "height": 600
  }
}
```


```json
{
  "name": "docs-img-crop",
  "width": 960,
  "height": 540,
  "duration": 4,
  "backgroundColor": "#1e1b31",
  "visuals": [
    {
      "type": "IMAGE",
      "src": "https://cdn.pixabay.com/photo/2023/06/04/20/21/cat-8040862_1280.jpg",
      "x": 280,
      "y": 120,
      "width": 400,
      "height": 300,
      "cropParams": {
        "x": 100,
        "y": 50,
        "width": 800,
        "height": 600
      }
    }
  ]
}
```

Recorded fixture: a cropped source image

[Watch rendered example](https://cdn.zvid.io/library/docs/img-crop.mp4)


### Rounded Corners And Filters

```json
{
  "type": "IMAGE",
  "src": "https://cdn.pixabay.com/photo/2022/11/05/22/11/channel-7572879_1280.jpg",
  "width": 300,
  "height": 200,
  "position": "bottom-right",
  "radius": {
    "tl": 10,
    "tr": 10,
    "bl": 10,
    "br": 10
  },
  "filter": {
    "brightness": -10,
    "hue-rotate": "30deg",
    "blur": 20
  }
}
```


```json
{
  "name": "docs-img-radius",
  "width": 960,
  "height": 540,
  "duration": 4,
  "backgroundColor": "#1e1b31",
  "visuals": [
    {
      "type": "IMAGE",
      "src": "https://cdn.pixabay.com/photo/2022/11/05/22/11/channel-7572879_1280.jpg",
      "width": 480,
      "height": 320,
      "position": "center-center",
      "radius": {
        "tl": 32,
        "tr": 32,
        "bl": 32,
        "br": 32
      }
    }
  ]
}
```

Recorded fixture: 32-pixel rounded corners, without the fragment's filters

[Watch rendered example](https://cdn.zvid.io/library/docs/img-radius.mp4)


## Related Pages

- [Video Elements](https://docs.zvid.io/docs/structure/video-elements/)
- [GIF Elements](https://docs.zvid.io/docs/structure/gif-elements/)
- [Animation Effects](https://docs.zvid.io/docs/structure/animations/)
- [FilterOptions](https://docs.zvid.io/docs/structure/properties/filter-options/)
- [CropParams](https://docs.zvid.io/docs/structure/properties/crop-params/)
- [ChromaKey](https://docs.zvid.io/docs/structure/properties/chroma-key/)
- [BorderRadius](https://docs.zvid.io/docs/structure/properties/border-radius/)