Skip to main content

GIF Elements

Complete reference for GIF elements with the Zvid, including animated GIF handling, timing control, and optimization.

Overview​

GIF elements allow you to add animated GIFs to your videos with precise timing control and rich visual properties. GIFs maintain their animation loops and can be positioned, scaled, and resized like other visual elements.

GIFItem Interface​

interface GIFItem {
  type: "GIF";
  src: string;
  x?: number;
  y?: number;
  width?: number;
  height?: number;
  anchor?: Anchor;
  position?: PositionPreset;
  resize?: ResizeMode;
  enterBegin?: number;
  enterEnd?: number;
  exitBegin?: number;
  exitEnd?: number;
  track?: number;
  opacity?: number;
  angle?: number;
  flipV?: boolean;
  flipH?: boolean;
  enterAnimation?: string | undefined;
  exitAnimation?: string | undefined;
  filter?: FilterOptions;
  chromaKey?: { color: string; similarity?: number; blend?: number };
  zoom?: boolean;
  cropParams?: CropParams;
}

Properties​

Required Properties​

PropertyTypeDescription
type"GIF"Element type identifier
srcstringGIF file path or URL

Position & Size Properties​

PropertyTypeDefaultDescription
xnumber0Horizontal position in pixels
ynumber0Vertical position in pixels
widthnumberSource widthGIF width in pixels
heightnumberSource heightGIF height in pixels
positionPositionPreset"custom"Position preset (overrides x, y)
anchorAnchortop-leftAnchor point for positioning
resizeResizeModeundefinedResize mode (overrides width, height)

Timing Properties​

PropertyTypeDefaultDescription
enterBeginnumber0Start time for entrance (seconds)
enterEndnumber0End time for entrance animation (seconds)
exitBeginnumberproject.durationStart time for exit animation (seconds)
exitEndnumberproject.durationEnd time for exit (seconds)

Visual Properties​

PropertyTypeDefaultDescription
tracknumber0Layer/track number (higher = on top)
opacitynumber1Transparency (0-1)
anglenumber0Rotation in degrees
flipVbooleanfalseFlip Vertically
flipHbooleanfalseFlip Horizontal
zoombooleanfalseAdd zoom effect

PositionPreset​

type PositionPreset =
  | "top-left"
  | "top-center"
  | "top-right"
  | "center-left"
  | "center-center"
  | "center-right"
  | "bottom-right"
  | "bottom-center"
  | "bottom-left"
  | "custom";

Anchor​

export type Anchor =
  | "top-left"
  | "top-center"
  | "top-right"
  | "center-left"
  | "center-center"
  | "center-right"
  | "bottom-left"
  | "bottom-center"
  | "bottom-right";

Animation Properties​

PropertyTypeDescription
enterAnimationstring | undefinedEntrance animation name
exitAnimationstring | undefinedExit animation name

Effect Properties​

PropertyTypeDescription
filterFilterOptionsGIF filters and effects
cropParamsCropParamsCropping configuration
chromaKeyChromaKeyChroma key color for green screen

ChromaKey interface​

interface ChromaKey {
  color: string;
  similarity?: number;
  blend?: number;
}

FilterOptions Interface​

interface FilterOptions {
  brightness?: number;
  contrast?: number;
  "hue-rotate"?: string;
  saturate?: number;
  blur?: string;
  invert?: boolean | number;
  colorTint?: string;
}

CropParams Interface​

interface CropParams {
  // horizontal start position (px)
  x: number;
  // vertical start position (px)
  y: number;
  // cropped width (px)
  width: number;
  // cropped height (px)
  height: number;
}

Zoom Property​

The zoom property adds a zoom effect to image elements.
When enabled, the image will smoothly zoom toward its center during its visible duration.

Usage​

// Boolean usage (uses default settings)
zoom: true;

Basic Examples​

Simple Animated GIF​

{
  type: "GIF",
  src: "https://media4.giphy.com/media/v1.Y2lkPTc5MGI3NjExcDVzeDhxNHozZHRvcjU4NDJ4dzRpY2xxdGJ3ZDJybGZ0ODg0dnVmbyZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/bbshzgyFQDqPHXBo4c/giphy.gif",
}

GIF with Position Preset​

{
  type: "GIF",
  src: "https://media4.giphy.com/media/v1.Y2lkPTc5MGI3NjExcDVzeDhxNHozZHRvcjU4NDJ4dzRpY2xxdGJ3ZDJybGZ0ODg0dnVmbyZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/bbshzgyFQDqPHXBo4c/giphy.gif",
  position: "top-right", // Automatically positions at top-right
  track: 2
}

GIF with Resize Mode​

{
  type: "GIF",
  src: "https://media3.giphy.com/media/v1.Y2lkPTc5MGI3NjExd2JzMmJ0a213anZ0bTR4ajVvdHhpaHZkOHpjcGx2M2twcHIxenpsciZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/i21tixUQEE7TEqwmYa/giphy.gif",
  resize: "contain", // Fill the 200x200 area, may crop
}

Corner Decoration with Position​

{
  type: "GIF",
  src: "https://media3.giphy.com/media/v1.Y2lkPTc5MGI3NjExbGN2aWpieDA4azh1YXB2NDZyM29scWs5dnF0bnUxYTNnNGcwYzhqeSZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/otnqsqqzmsw7K/giphy.gif",
  width: 150,
  height: 100,
  position: "top-right", // Automatically positions at bottom-right
  opacity: 0.7,
  track: 15
}

Advanced Examples​

Cropped GIF​

{
  type: "GIF",
  src: "https://media4.giphy.com/media/v1.Y2lkPTc5MGI3NjExcDVzeDhxNHozZHRvcjU4NDJ4dzRpY2xxdGJ3ZDJybGZ0ODg0dnVmbyZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/bbshzgyFQDqPHXBo4c/giphy.gif",
  x: 400,
  y: 200,
  width: 300,
  height: 200,
  cropParams: {
    x: 50,     // Start crop 50px from left
    y: 25,     // Start crop 25px from top
    width: 400, // Crop 400px wide
    height: 300 // Crop 300px tall
  },
}

Corner Decoration GIF​

{
  type: "GIF",
  src: "https://media3.giphy.com/media/v1.Y2lkPTc5MGI3NjExbGN2aWpieDA4azh1YXB2NDZyM29scWs5dnF0bnUxYTNnNGcwYzhqeSZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/otnqsqqzmsw7K/giphy.gif",
  position: "bottom-right",
  width: 150,
  height: 100,
  opacity: 0.7,
  track: 15, // Very high track for decoration
}

Common Use Cases​

Reaction GIFs​

{
  type: "GIF",
  src: "https://media3.giphy.com/media/v1.Y2lkPTc5MGI3NjExd2JzMmJ0a213anZ0bTR4ajVvdHhpaHZkOHpjcGx2M2twcHIxenpsciZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/i21tixUQEE7TEqwmYa/giphy.gif",
  position: "center-center",
  track: 10
}

Loading Animations​

{
  type: "GIF",
  src: "https://media4.giphy.com/media/v1.Y2lkPTc5MGI3NjExeHZuNWJjdjJ4YmZxbW1nOTZhMnhwcGZ1aTV2b3A1YzltOG50eXV5ZiZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/3oEjI6SIIHBdRxXI40/giphy.gif",
  position: "center-center",
  track: 20
}

Next Steps​