API Reference

The Liveposter library exposes a single main class, ImageAnimator, which handles all animation modes and configuration.

ImageAnimator Class

Constructor

import ImageAnimator from 'liveposter';

const animator = new ImageAnimator(config);

Parameters:

config (Object): Configuration object containing poster specification

Configuration Object

The configuration object follows the Poster Spec Format. Key properties include:

{
  container: "#poster",           // CSS selector or HTMLElement
  mode: "diaporama",              // Animation mode
  loop: true,                     // Whether to loop
  timing: {
    duration: 3000,               // Display duration (ms)
    transition: 500               // Transition duration (ms)
  },
  effects: { /* mode-specific */ },
  images: [ /* image array */ ],
  overlays: [ /* overlay array */ ]
}

See the Poster Spec Format for complete configuration schema.

Instance Methods

init()

Initializes the animator, preloads images, and prepares the container.

await animator.init();

Returns: Promise<void>

Example:

const animator = new ImageAnimator(config);
await animator.init();
// Animator is now ready and playing

Notes:

Must be called before using other methods
Preloads all images before resolving
Automatically starts playing if autostart is true (default)

next()

Advances to the next slide.

animator.next();

Returns: void

Example:

// Advance to next slide manually
animator.next();

Notes:

If at the last slide and loop: true, returns to first slide
If at the last slide and loop: false, does nothing

previous()

Goes back to the previous slide.

animator.previous();

Returns: void

Example:

// Go to previous slide
animator.previous();

Notes:

If at the first slide and loop: true, goes to last slide
If at the first slide and loop: false, does nothing

pause()

Pauses the animation.

animator.pause();

Returns: void

Example:

// Pause the slideshow
animator.pause();

Notes:

Only affects automatic slideshows (diaporama, pan, zoom)
Does not affect interactive modes (lenticular, parallax)

resume()

Resumes the animation from a paused state.

animator.resume();

Returns: void

Example:

// Resume after pausing
animator.resume();

goToSlide(index)

Jumps to a specific slide by index.

animator.goToSlide(2); // Go to third slide (0-indexed)

Parameters:

index (number): Zero-based slide index

Returns: void

Example:

// Jump to first slide
animator.goToSlide(0);

// Jump to specific slide
animator.goToSlide(5);

destroy()

Cleans up the animator, removes event listeners, and clears the container.

animator.destroy();

Returns: void

Example:

// Clean up when done
animator.destroy();

Notes:

Removes all DOM elements created by the animator
Removes all event listeners
Clears overlays
Should be called when removing the animator

Event System

The animator emits events that you can subscribe to for integration with your UI.

on(eventName, callback)

Subscribes to an event.

animator.on('slideChange', (data) => {
  console.log('Slide changed:', data);
});

Parameters:

eventName (string): Name of the event (‘slideChange’ or ‘slideProgress’)
callback (Function): Event handler function

Returns: void

off(eventName, callback)

Unsubscribes from an event.

const handler = (data) => console.log(data);
animator.on('slideChange', handler);
animator.off('slideChange', handler);

Parameters:

eventName (string): Name of the event
callback (Function): Event handler function to remove

Returns: void

Events

slideChange

Fired when the current slide changes.

Event data:

{
  currentIndex: 2,    // New slide index
  previousIndex: 1    // Previous slide index
}

Example:

animator.on('slideChange', ({ currentIndex, previousIndex }) => {
  console.log(`Changed from slide ${previousIndex} to ${currentIndex}`);

  // Update UI indicators
  updatePaginationDots(currentIndex);
});

Use cases:

Updating pagination indicators
Triggering analytics events
Syncing with other UI elements
Custom slide change animations

slideProgress

Fired during slide display, providing animation progress.

Event data:

{
  currentIndex: 1,    // Current slide index
  progress: 0.5       // Progress through current slide (0-1)
}

Example:

animator.on('slideProgress', ({ currentIndex, progress }) => {
  // Update a progress bar
  progressBar.style.width = `${progress * 100}%`;

  // Trigger effects at specific progress points
  if (progress > 0.5 && !triggered) {
    triggerMidSlideEffect();
    triggered = true;
  }
});

Use cases:

Progress bars
Time-based UI updates
Triggering effects at specific points
Syncing audio/video

Note: Only emitted by automatic slideshow modes (diaporama, pan, zoom). Interactive modes (lenticular, parallax) do not emit this event.

Properties

currentIndex

Current slide index (read-only).

const index = animator.currentIndex;
console.log(`Currently on slide ${index + 1}`);

Type: number

imageCount

Total number of images (read-only).

const total = animator.imageCount;
console.log(`Total slides: ${total}`);

Type: number

isPaused

Whether the animator is currently paused (read-only).

if (animator.isPaused) {
  console.log('Animator is paused');
}

Type: boolean

Complete Example

Here’s a complete example showing all major API features:

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="node_modules/liveposter/dist/animator.css" />
  <style>
    #slideshow { width: 100vw; height: 100vh; }
    #controls { position: fixed; bottom: 20px; left: 50%; transform: translateX(-50%); }
    #progress-bar { position: fixed; top: 0; left: 0; height: 3px; background: #00ff00; }
  </style>
</head>
<body>
  <div id="slideshow"></div>
  <div id="controls">
    <button id="prev">Previous</button>
    <button id="pause">Pause</button>
    <button id="next">Next</button>
  </div>
  <div id="progress-bar"></div>

  <script type="module">
    import ImageAnimator from 'liveposter';

    const config = {
      container: "#slideshow",
      mode: "diaporama",
      loop: true,
      timing: {
        duration: 3000,
        transition: 500
      },
      effects: {
        type: "fade",
        easing: "ease-in-out"
      },
      images: [
        { src: "image1.jpg", alt: "Image 1" },
        { src: "image2.jpg", alt: "Image 2" },
        { src: "image3.jpg", alt: "Image 3" }
      ]
    };

    // Initialize animator
    const animator = new ImageAnimator(config);
    await animator.init();

    // Set up controls
    document.getElementById('prev').addEventListener('click', () => {
      animator.previous();
    });

    document.getElementById('next').addEventListener('click', () => {
      animator.next();
    });

    let paused = false;
    document.getElementById('pause').addEventListener('click', (e) => {
      if (paused) {
        animator.resume();
        e.target.textContent = 'Pause';
      } else {
        animator.pause();
        e.target.textContent = 'Resume';
      }
      paused = !paused;
    });

    // Listen to events
    animator.on('slideChange', ({ currentIndex, previousIndex }) => {
      console.log(`Slide changed: ${previousIndex} → ${currentIndex}`);
    });

    animator.on('slideProgress', ({ currentIndex, progress }) => {
      // Update progress bar
      const progressBar = document.getElementById('progress-bar');
      progressBar.style.width = `${progress * 100}%`;
    });

    // Cleanup on page unload
    window.addEventListener('beforeunload', () => {
      animator.destroy();
    });
  </script>
</body>
</html>

TypeScript Support

While Liveposter is written in JavaScript, it includes JSDoc type definitions for IDE autocomplete:

/**
 * @typedef {Object} PosterConfig
 * @property {string|HTMLElement} container - Container selector or element
 * @property {string} mode - Animation mode
 * @property {boolean} [loop=true] - Whether to loop
 * @property {TimingConfig} timing - Timing configuration
 * @property {Object} effects - Effects configuration
 * @property {ImageConfig[]} images - Array of image configurations
 * @property {OverlayConfig[]} [overlays] - Array of overlay configurations
 */

These types are available in your IDE for autocomplete and documentation.

Next Steps

Learn about Animation Modes
Explore Overlays for enhanced visuals
Understand Effects for transitions
Check the Poster Spec Format for complete configuration options