GIF Elements

Complete reference for GIF elements in the Zvid Package, 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 | null;
  exitAnimation?: string | null;
  cropParams?: CropParams;
}

Properties

Required Properties

Property	Type	Description
type	"GIF"	Element type identifier
src	string	GIF file path or URL

Position & Size Properties

Property	Type	Default	Description
x	number	0	Horizontal position in pixels
y	number	0	Vertical position in pixels
width	number	Source width	GIF width in pixels
height	number	Source height	GIF height in pixels
position	PositionPreset	"custom"	Position preset (overrides x, y)
resize	ResizeMode	null	Resize mode (overrides width, height)

Timing Properties

Property	Type	Default	Description
enterBegin	number	0	Start time for entrance (seconds)
enterEnd	number	0	End time for entrance animation (seconds)
exitBegin	number	project.duration	Start time for exit animation (seconds)
exitEnd	number	project.duration	End time for exit (seconds)

Visual Properties

Property	Type	Default	Description
track	number	0	Layer/track number (higher = on top)
opacity	number	1	Transparency (0-1)
angle	number	0	Rotation in degrees
flipV	boolean	false	Flip Vertically
flipH	boolean	false	Flip Horizontal

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

Property	Type	Default	Description
enterAnimation	string | null	null	Entrance animation name
exitAnimation	string | null	null	Exit animation name

Effect Properties

Property	Type	Default	Description
cropParams	CropParams	null	Cropping configuration

For now animation doesn't work with GIF, but I'm working on it

GIF the slowest element to process, but I'm working to optimize it.

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;
}

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
}

Performance Considerations

File Size Optimization

1. Resolution: Use appropriate GIF dimensions for your use case
2. Frame Count: Fewer frames = smaller file size
3. Color Palette: Reduced colors = better compression
4. Duration: Shorter loops are more efficient

Best Practices

Visual Design

1. Contrast: Ensure GIFs don't clash with background content
2. Size: Use appropriate dimensions for the visual impact needed
3. Placement: Position GIFs to enhance, not distract from main content
4. Transparency: Use opacity for subtle effects

Technical Guidelines

1. Format: Ensure GIFs are properly optimized before use
2. Looping: Consider how GIF loops align with your content timing
3. Layering: Use track numbers to control GIF stacking order
4. Caching: URLs are cached for better performance

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
}

Supported GIF Features

Animation Properties

• Frame Rate: Maintains original GIF frame timing
• Loop Count: Infinite looping during display duration
• Transparency: Supports GIF transparency
• Interlacing: Handles interlaced GIFs

Limitations

• No Audio: GIFs don't contain audio tracks
• Color Depth: Limited to 256 colors per frame
• Compression: Less efficient than modern video formats

Troubleshooting

Common Issues

1. Large File Sizes: Optimize GIFs before use
2. Slow Loading: Consider using video formats for large animations
3. Quality Loss: Use appropriate source resolution
4. Timing Issues: Account for GIF loop duration in planning

Performance Tips

1. Preload: Popular GIFs are cached automatically
2. Compression: Use tools to optimize GIF file sizes
3. Alternatives: Consider MP4 for large or long animations
4. Testing: Preview GIFs in context before final render

Related Pages

• Image Elements - Static image handling
• Video Elements - Video animation alternatives
• Animation Effects - Element animations

Next Steps

• SVG Elements - Vector graphics and shapes
• Animation Effects - Learn about element animations