Animation Modes

Liveposter offers six distinct animation modes, each designed for different use cases and visual effects. This guide covers each mode in detail with configuration examples and best practices.

Overview

Mode	Type	Best For	Input-Driven
Diaporama	Automatic	Classic slideshows	No
Pan Slideshow	Automatic	Wide panoramic images	No
Zoom Slideshow	Automatic	Cinematic presentations	No
Lenticular	Interactive	3D-like effects	Yes
Parallax Layers	Interactive	Depth scenes	Yes

Diaporama (Crossfade)

The diaporama mode provides smooth crossfade transitions between images. It’s the most versatile mode, supporting both instant cuts (hard cuts) and smooth fades.

What It Is

Diaporama creates elegant transitions by fading one image out while simultaneously fading the next image in. You can control the transition speed to create anything from instant cuts to long, smooth dissolves.

When to Use

Classic photo galleries
Professional presentations
Product showcases with smooth transitions
Any scenario requiring elegant image changes

Visual Effect

Images smoothly dissolve from one to the next. The current image becomes progressively transparent while the next image fades in underneath, creating a professional crossfade effect.

Configuration Options

{
  "mode": "diaporama",
  "timing": {
    "duration": 2000,     // How long each image displays (ms)
    "transition": 500     // Fade duration (ms), 0 = instant cut
  },
  "effects": {
    "type": "fade",
    "easing": "ease-in-out"  // Transition timing function
  }
}

Key Parameters

duration: Display time for each image in milliseconds
transition: Fade duration (0ms = instant cut/hard cut)
easing: Timing function for the transition
- linear: Constant speed fade
- ease-in: Starts slow, accelerates
- ease-out: Starts fast, decelerates
- ease-in-out: Smooth acceleration and deceleration (recommended)

Example 1: Classic Crossfade

Smooth 500ms crossfade between images:

{
  "container": "#slideshow",
  "mode": "diaporama",
  "loop": true,
  "timing": {
    "duration": 3000,
    "transition": 500
  },
  "effects": {
    "type": "fade",
    "easing": "ease-in-out"
  },
  "images": [
    { "src": "landscape1.jpg", "alt": "Mountain view" },
    { "src": "landscape2.jpg", "alt": "Ocean sunset" },
    { "src": "landscape3.jpg", "alt": "Forest path" }
  ]
}

Example 2: Hard Cut (Instant Transitions)

Instant transitions with no fade:

{
  "container": "#slideshow",
  "mode": "diaporama",
  "loop": true,
  "timing": {
    "duration": 2000,
    "transition": 0  // 0ms = instant cut
  },
  "effects": {
    "type": "fade"
  },
  "images": [
    { "src": "product1.jpg", "alt": "Product view 1" },
    { "src": "product2.jpg", "alt": "Product view 2" },
    { "src": "product3.jpg", "alt": "Product view 3" }
  ]
}

Example 3: Per-Image Timing

Override timing for specific images:

{
  "container": "#slideshow",
  "mode": "diaporama",
  "timing": {
    "duration": 2000,
    "transition": 500
  },
  "images": [
    {
      "src": "hero.jpg",
      "alt": "Hero image",
      "timing": {
        "duration": 5000,    // Show longer
        "transition": 1000   // Slower fade
      }
    },
    { "src": "image2.jpg", "alt": "Image 2" },
    { "src": "image3.jpg", "alt": "Image 3" }
  ]
}

Tips and Best Practices

Hard cuts vs. fades: Use transition: 0 for hard cuts (fast-paced content), 300-800ms for smooth crossfades
Easing: ease-in-out provides the most natural-looking transitions
Duration: 2-4 seconds per image works well for most content
Performance: Crossfades are GPU-accelerated and perform well even at 4K resolution
Long fades: Transitions longer than 1000ms can feel sluggish unless intentional

Pan Slideshow (Continuous Panning)

The pan-slideshow mode enables continuous panning across wide images, perfect for panoramic shots or horizontal/vertical reveals.

What It Is

Pan slideshow animates the viewport across a larger image, creating a smooth scrolling effect. The image remains stationary while the visible area moves across it.

When to Use

Wide panoramic photographs
Horizontal banners or timelines
Vertical scrolling content
Revealing large images progressively

Visual Effect

The viewport smoothly travels across a wide image from one side to the other, creating a camera pan effect. The motion is fluid and continuous throughout the duration.

Configuration Options

{
  "mode": "pan-slideshow",
  "images": [
    {
      "src": "wide-panorama.jpg",
      "timing": {
        "duration": 3000,
        "transition": 3000  // Pan duration matches display
      },
      "effects": {
        "type": "pan",
        "direction": "right",  // or "left", "up", "down"
        "easing": "linear",
        "distance": "100%"
      },
      "viewport": {
        "width": "1080px",
        "height": "1920px",
        "overflow": "hidden"
      }
    }
  ]
}

Key Parameters

direction: Pan direction (left, right, up, down)
easing: Usually linear for constant speed panning
distance: How far to pan (percentage or pixels)
viewport: Defines the visible area size

Example 1: Horizontal Pan

Pan across a wide landscape:

{
  "container": "#slideshow-pan",
  "mode": "pan-slideshow",
  "loop": true,
  "images": [
    {
      "src": "panorama-3840x1920.jpg",
      "alt": "Wide panorama",
      "timing": {
        "duration": 5000,
        "transition": 5000
      },
      "effects": {
        "type": "pan",
        "direction": "right",
        "easing": "linear",
        "distance": "100%"
      },
      "viewport": {
        "width": "1080px",
        "height": "1920px",
        "overflow": "hidden"
      }
    }
  ]
}

Example 2: Mixed Pan and Static

Combine panning images with static slides:

{
  "container": "#slideshow",
  "mode": "pan-slideshow",
  "loop": true,
  "images": [
    {
      "src": "wide-image.jpg",
      "alt": "Panning image",
      "timing": {
        "duration": 4000,
        "transition": 4000
      },
      "effects": {
        "type": "pan",
        "direction": "left",
        "easing": "linear"
      }
    },
    {
      "src": "static-image.jpg",
      "alt": "Static slide",
      "timing": {
        "duration": 2000,
        "transition": 0  // Hard cut to static
      },
      "effects": {
        "type": "cut"
      }
    }
  ]
}

Tips and Best Practices

Image size: Use images wider (for horizontal pan) or taller (for vertical pan) than your viewport
Speed: Match transition duration to display duration for continuous motion
Easing: Use linear for constant-speed panning; other easings create acceleration/deceleration
Aspect ratio: For vertical displays (1080x1920), use 3840x1920 images for horizontal pans
File size: Large panoramic images can be heavy; optimize for web
Direction: Right-to-left pan (direction: “left”) is often more comfortable for viewers

Zoom Slideshow (Ken Burns Effect)

The zoom-slideshow mode creates a cinematic Ken Burns effect by slowly zooming in or out on images.

What It Is

Named after the documentary filmmaker Ken Burns, this effect slowly zooms into or out of still images, adding motion and visual interest to static photography.

When to Use

Documentary-style presentations
Storytelling and narrative content
Adding drama to still photographs
Cinematic photo galleries

Visual Effect

Images gradually scale up (zoom in) or down (zoom out) over time, often focusing on a specific area of the image. The effect creates the illusion of camera movement.

Configuration Options

{
  "mode": "zoom-slideshow",
  "timing": {
    "duration": 3000,
    "transition": 2000
  },
  "effects": {
    "type": "zoom",
    "scale": 1.3,           // End scale (1.0 = original size)
    "origin": "center",     // Zoom focal point
    "easing": "ease-in-out"
  }
}

Key Parameters

scale: Target zoom level (1.0 = no zoom, 1.3 = 30% larger)
origin: Zoom focal point
- center: Zoom from center
- top-left, top-right, bottom-left, bottom-right: Zoom from corner
- Custom: "50% 50%" for precise positioning
easing: Zoom speed curve
- ease-in: Accelerating zoom
- ease-out: Decelerating zoom
- ease-in-out: Smooth acceleration and deceleration

Example 1: Center Zoom

Smooth zoom into the center of images:

{
  "container": "#slideshow",
  "mode": "zoom-slideshow",
  "loop": true,
  "timing": {
    "duration": 4000,
    "transition": 3000
  },
  "effects": {
    "type": "zoom",
    "scale": 1.3,
    "origin": "center",
    "easing": "ease-in-out"
  },
  "images": [
    { "src": "landscape1.jpg", "alt": "Mountain vista" },
    { "src": "landscape2.jpg", "alt": "Ocean view" },
    { "src": "landscape3.jpg", "alt": "City skyline" }
  ]
}

Example 2: Variable Zoom Per Image

Different zoom effects for each image:

{
  "container": "#slideshow",
  "mode": "zoom-slideshow",
  "loop": true,
  "timing": {
    "duration": 3000,
    "transition": 2000
  },
  "images": [
    {
      "src": "portrait1.jpg",
      "alt": "Portrait",
      "effects": {
        "type": "zoom",
        "scale": 1.5,
        "origin": "top-left",
        "easing": "ease-out"
      }
    },
    {
      "src": "landscape1.jpg",
      "alt": "Landscape",
      "effects": {
        "type": "zoom",
        "scale": 1.2,
        "origin": "bottom-right",
        "easing": "ease-in"
      }
    }
  ]
}

Tips and Best Practices

Scale range: 1.1-1.4 creates subtle movement; 1.5+ is more dramatic
Duration: Slower zooms (3-5 seconds) feel more cinematic
Easing: ease-in-out provides the most natural motion
Origin: Vary zoom origins to create visual diversity
Resolution: Use high-resolution images since zooming reveals detail
Subtle is better: Overly aggressive zooms can feel nauseating
Combine with position: Consider which part of the image will be centered when zoomed

Lenticular (Input-Driven Switching)

The lenticular mode creates an interactive effect where mouse position (or device tilt) switches between different images, simulating lenticular printing.

What It Is

Lenticular mode displays different images based on viewer input, typically mouse position. As you move your mouse across the container, different images are revealed, creating a 3D-like or “holographic” effect.

When to Use

Interactive product displays (showing different angles)
Before/after comparisons
Multi-view displays
Interactive kiosks
360-degree product views

Visual Effect

Moving your mouse horizontally across the image switches between different views. The effect mimics lenticular prints where the image appears to change based on viewing angle.

Configuration Options

{
  "mode": "lenticular",
  "loop": false,
  "input": {
    "type": "mouseX",        // or "mouseY", "tiltX", "tiltY"
    "mapping": "linear",     // or "eased"
    "bounds": [0, 1]
  },
  "timing": {
    "transition": 50         // Quick transitions for responsiveness
  },
  "effects": {
    "type": "fade",
    "easing": "ease-out"
  }
}

Key Parameters

input.type: Input source
- mouseX: Horizontal mouse position
- mouseY: Vertical mouse position
- tiltX: Device tilt horizontal (mobile)
- tiltY: Device tilt vertical (mobile)
input.mapping: How input maps to images
- linear: Direct 1:1 mapping
- eased: Smoothed, less jittery
transition: Response speed (lower = more responsive)

Example 1: Product Rotation

Show different angles of a product:

{
  "container": "#product-viewer",
  "mode": "lenticular",
  "loop": false,
  "input": {
    "type": "mouseX",
    "mapping": "linear",
    "bounds": [0, 1]
  },
  "timing": {
    "transition": 50
  },
  "effects": {
    "type": "fade",
    "easing": "ease-out"
  },
  "images": [
    { "src": "product-angle-0.jpg", "alt": "Front view" },
    { "src": "product-angle-45.jpg", "alt": "Angle 45°" },
    { "src": "product-angle-90.jpg", "alt": "Side view" },
    { "src": "product-angle-135.jpg", "alt": "Angle 135°" },
    { "src": "product-angle-180.jpg", "alt": "Back view" }
  ]
}

Example 2: Before/After Comparison

Interactive before and after views:

{
  "container": "#comparison",
  "mode": "lenticular",
  "input": {
    "type": "mouseX",
    "mapping": "eased"
  },
  "timing": {
    "transition": 100
  },
  "images": [
    { "src": "before.jpg", "alt": "Before" },
    { "src": "after.jpg", "alt": "After" }
  ]
}

Tips and Best Practices

Number of images: 3-8 images work well; more can feel overwhelming
Image consistency: Keep camera position consistent between shots for smooth transitions
Transition speed: 50-150ms provides good responsiveness without jitter
Mapping: Use eased mapping for smoother, less jumpy transitions
Mobile: Consider touch/drag support for mobile devices
Instructions: Add visual hints (e.g., “Move mouse to explore”) for users
Lighting: Maintain consistent lighting across all angles

Parallax Layers (Multi-Layer Depth)

The parallax-layers mode creates depth by moving multiple image layers at different speeds based on input, simulating 3D perspective.

What It Is

Parallax layers use the visual principle that closer objects appear to move faster than distant objects. Multiple images are stacked at different depths and move at different rates in response to mouse movement or device tilt.

When to Use

Creating depth in flat designs
Interactive storytelling
Immersive hero sections
Gaming interfaces
Art installations

Visual Effect

Multiple layers of images move at different speeds as you move your mouse, creating an illusion of depth. Foreground layers move more than background layers, mimicking real-world perspective.

Configuration Options

{
  "mode": "parallax-layers",
  "loop": false,
  "input": {
    "type": "mouseX",
    "mapping": "eased"
  },
  "effects": {
    "type": "parallax",
    "easing": "ease-out"
  },
  "images": [
    {
      "src": "background.jpg",
      "layer": 0,
      "effects": {
        "intensity": 10,    // Minimal movement
        "axis": "x"         // or "y" or "both"
      }
    },
    {
      "src": "midground.jpg",
      "layer": 1,
      "effects": {
        "intensity": 30     // Medium movement
      }
    },
    {
      "src": "foreground.jpg",
      "layer": 2,
      "effects": {
        "intensity": 60     // Maximum movement
      }
    }
  ]
}

Key Parameters

layer: Layer depth (0 = background, higher = foreground)
intensity: Movement amount (0-100, higher = more movement)
axis: Movement direction (x, y, or both)
input.type: Input source (mouseX, mouseY, tiltX, tiltY)

Example 1: Three-Layer Scene

Classic three-layer parallax:

{
  "container": "#parallax-scene",
  "mode": "parallax-layers",
  "loop": false,
  "input": {
    "type": "mouseX",
    "mapping": "eased"
  },
  "effects": {
    "type": "parallax",
    "easing": "ease-out"
  },
  "images": [
    {
      "src": "mountains-far.png",
      "alt": "Distant mountains",
      "layer": 0,
      "effects": {
        "intensity": 10,
        "axis": "x"
      }
    },
    {
      "src": "mountains-mid.png",
      "alt": "Mid-distance mountains",
      "layer": 1,
      "effects": {
        "intensity": 30,
        "axis": "x"
      }
    },
    {
      "src": "trees-foreground.png",
      "alt": "Foreground trees",
      "layer": 2,
      "effects": {
        "intensity": 60,
        "axis": "x"
      }
    }
  ]
}

Example 2: With Overlays

Parallax with additional overlay elements:

{
  "container": "#parallax-scene",
  "mode": "parallax-layers",
  "input": {
    "type": "mouseX",
    "mapping": "eased"
  },
  "overlays": [
    {
      "type": "image",
      "src": "logo.png",
      "opacity": 0.8,
      "position": "top-right",
      "width": "200px",
      "height": "200px",
      "zIndex": 15
    }
  ],
  "images": [
    {
      "src": "background.jpg",
      "layer": 0,
      "effects": { "intensity": 10 }
    },
    {
      "src": "foreground.png",
      "layer": 1,
      "effects": { "intensity": 50 }
    }
  ]
}

Tips and Best Practices

Layer count: 2-4 layers work best; more can be confusing
Intensity scaling: Use exponential scaling (10, 30, 60) not linear (20, 40, 60)
Transparency: Use PNG images with transparency for foreground layers
Composition: Design each layer to look good when combined
Subtle movement: Start with low intensities and increase gradually
Performance: Keep layer images optimized; many layers can impact performance
Axis choice: Horizontal (x) movement is most intuitive for mouse input
Mobile: Test on mobile devices; device tilt can be more sensitive

Choosing the Right Mode

Decision Flow

Is it interactive?
- Yes → Lenticular or Parallax Layers
- No → Continue
Do you need motion on still images?
- Yes → Pan or Zoom
- No → Diaporama
What type of images do you have?
- Wide panoramas → Pan Slideshow
- Standard photos → Zoom or Diaporama
- Multiple angles → Lenticular
- Layered design → Parallax Layers

Mode Comparison

Aspect	Diaporama	Pan	Zoom	Lenticular	Parallax
Interactivity	None	None	None	High	High
Motion	Fade	Continuous	Scaling	Switching	Multi-layer
Best For	General	Wide images	Drama	Products	Depth
Complexity	Simple	Medium	Simple	Medium	High
Performance	Excellent	Good	Good	Excellent	Good

Next Steps

Explore configuration options for advanced customization
See examples for complete implementations
Learn about overlays to enhance your animations
Check out the CLI guide for development workflow

Additional Resources

Demo specs: /packages/demo-server/public/specs/ in the repository
Live examples: Run npx liveposter to see all modes in action
API reference: Complete configuration schema documentation