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

# GIF Elements

`GIF` elements add animated GIF assets to a project. The hosted API accepts GIFs as media-like visual elements, including timing, transform, resize, zoom, crop, filters, and chroma key options.

## Interface

```typescript
interface GIFItem {
  type: "GIF";
  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;
  zoom?: boolean | { depth?: number };
  radius?: BorderRadius;
}
```

## Required Fields

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

## Properties

`GIF` elements behave like [images](https://docs.zvid.io/docs/structure/image-elements/): they share the
[common element properties](https://docs.zvid.io/docs/structure/common-properties/) and 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/). The GIF's own animation loops for
the element's visible duration.

## Examples

These are **visual element fragments** for a video project's `payload.visuals`.
`GIF` elements are rejected in image projects; use a static image instead.
The recorded preview includes a background and its own GIF placement; use its
full payload for that exact composition.

### Simple GIF

```json
{
  "type": "GIF",
  "src": "https://media.giphy.com/media/3oEjI6SIIHBdRxXI40/giphy.gif",
  "position": "center-center",
  "track": 10
}
```


```json
{
  "name": "docs-gif-overlay",
  "width": 960,
  "height": 540,
  "duration": 5,
  "backgroundColor": "#000000",
  "visuals": [
    {
      "type": "VIDEO",
      "src": "https://cdn.pixabay.com/video/2025/06/09/284566_large.mp4",
      "resize": "cover",
      "width": 960,
      "height": 540,
      "volume": 0
    },
    {
      "type": "GIF",
      "src": "https://media.giphy.com/media/3oEjI6SIIHBdRxXI40/giphy.gif",
      "width": 260,
      "height": 260,
      "resize": "contain",
      "position": "bottom-left",
      "track": 10
    }
  ]
}
```

Recorded fixture: a GIF over a video background

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


### Resized GIF

```json
{
  "type": "GIF",
  "src": "https://media.giphy.com/media/3oEjI6SIIHBdRxXI40/giphy.gif",
  "width": 300,
  "height": 300,
  "resize": "contain",
  "position": "bottom-right",
  "opacity": 0.8
}
```

### Cropped GIF

```json
{
  "type": "GIF",
  "src": "https://media.giphy.com/media/3oEjI6SIIHBdRxXI40/giphy.gif",
  "width": 300,
  "height": 200,
  "cropParams": {
    "x": 50,
    "y": 25,
    "width": 400,
    "height": 300
  }
}
```

## Related Pages

- [Image Elements](https://docs.zvid.io/docs/structure/image-elements/)
- [Video Elements](https://docs.zvid.io/docs/structure/video-elements/)
- [Animation Effects](https://docs.zvid.io/docs/structure/animations/)
- [Property Reference](https://docs.zvid.io/docs/structure/properties/position/)