Getting Started

Liveposter is a JSON-driven JavaScript animation library for creating sophisticated image transitions and effects. It’s framework-agnostic, lightweight, and easy to use - perfect for creating dynamic visual displays, digital signage, and interactive presentations.

Quick Start

The fastest way to try Liveposter is to run it directly with npx - no installation required!

Try the Demo

npm

npx liveposter

pnpm

pnpm dlx liveposter

yarn

yarn dlx liveposter

bun

bunx liveposter

This will start a demo server at http://localhost:3000 showcasing all available animation modes.

Installation

For Library Use

Install Liveposter in your project:

npm

npm install liveposter

pnpm

pnpm add liveposter

yarn

yarn add liveposter

bun

bun add liveposter

Using the CLI Tool

The recommended way to use the CLI is with npx - no installation required!

Basic Usage

Running the Demo

Start the built-in demo showcasing all animation modes:

npx

npx liveposter
# or explicitly
npx liveposter demo

pnpm

pnpm dlx liveposter
# or explicitly
pnpm dlx liveposter demo

yarn

yarn dlx liveposter
# or explicitly
yarn dlx liveposter demo

bun

bunx liveposter
# or explicitly
bunx liveposter demo

Serving a Single Poster Spec

Display a specific poster configuration:

npx

npx liveposter path/to/your-poster.json

pnpm

pnpm dlx liveposter path/to/your-poster.json

yarn

yarn dlx liveposter path/to/your-poster.json

bun

bunx liveposter path/to/your-poster.json

Serving a Poster List

Display multiple posters in a fullscreen layout with navigation:

npx

npx liveposter path/to/poster-list.json

pnpm

pnpm dlx liveposter path/to/poster-list.json

yarn

yarn dlx liveposter path/to/poster-list.json

bun

bunx liveposter path/to/poster-list.json

A poster list is a JSON array of spec file paths:

[
  "specs/slideshow.json",
  "specs/parallax.json",
  {
    "spec": "specs/zoom.json",
    "title": "Custom Title",
    "description": "Optional description"
  }
]

Development Mode with Hot-Reload

When developing posters, use development mode for automatic browser reload on file changes:

npx

# Watch a poster spec with auto-reload
npx liveposter dev path/to/your-poster.json

# Watch a poster list
npx liveposter dev path/to/poster-list.json

# Watch the default demo
npx liveposter dev

pnpm

# Watch a poster spec with auto-reload
pnpm dlx liveposter dev path/to/your-poster.json

# Watch a poster list
pnpm dlx liveposter dev path/to/poster-list.json

# Watch the default demo
pnpm dlx liveposter dev

yarn

# Watch a poster spec with auto-reload
yarn dlx liveposter dev path/to/your-poster.json

# Watch a poster list
yarn dlx liveposter dev path/to/poster-list.json

# Watch the default demo
yarn dlx liveposter dev

bun

# Watch a poster spec with auto-reload
bunx liveposter dev path/to/your-poster.json

# Watch a poster list
bunx liveposter dev path/to/poster-list.json

# Watch the default demo
bunx liveposter dev

The dev mode automatically reloads your browser when you modify:

• Poster spec JSON files
• Image assets
• HTML/CSS files
• Any files in the spec’s directory

Port Configuration

By default, Liveposter runs on port 3000. You can customize the port in three ways:

Option 1: Environment Variable

npx

PORT=8080 npx liveposter dev my-poster.json

pnpm

PORT=8080 pnpm dlx liveposter dev my-poster.json

yarn

PORT=8080 yarn dlx liveposter dev my-poster.json

bun

PORT=8080 bunx liveposter dev my-poster.json

Option 2: .env File in Project Directory

Create a .env file in your project directory (where you run the command):

echo "PORT=8080" > .env

Then run Liveposter normally - it will use the port from your .env file:

npx liveposter dev my-poster.json

Option 3: .env File in Package Directory

For repository development, create .env in packages/demo-server/:

echo "PORT=8080" > packages/demo-server/.env
npm run dev

Priority Order

Liveposter checks these locations in order:

1. PORT environment variable (highest priority)
2. .env in current working directory
3. .env in package directory
4. Default: 3000 (if none set)

Your First Poster

Let’s create a simple slideshow from scratch.

1. Create a Poster Spec

Create a file called my-first-poster.json:

{
  "container": "#poster",
  "mode": "diaporama",
  "loop": true,
  "timing": {
    "duration": 3000,
    "transition": 500
  },
  "effects": {
    "type": "fade",
    "easing": "ease-in-out"
  },
  "images": [
    { "src": "https://picsum.photos/1080/1920?random=1", "alt": "Image 1" },
    { "src": "https://picsum.photos/1080/1920?random=2", "alt": "Image 2" },
    { "src": "https://picsum.photos/1080/1920?random=3", "alt": "Image 3" }
  ]
}

2. Run It Locally

npx

npx liveposter dev my-first-poster.json

pnpm

pnpm dlx liveposter dev my-first-poster.json

yarn

yarn dlx liveposter dev my-first-poster.json

bun

bunx liveposter dev my-first-poster.json

Open http://localhost:3000 in your browser. You’ll see a smooth crossfade slideshow!

3. Understanding the Output

Your poster will:

• Display three images in sequence
• Use smooth fade transitions (500ms)
• Show each image for 3 seconds
• Loop continuously

Try modifying the spec:

• Change mode to "hardcut-slideshow" for instant transitions
• Adjust timing.duration to control display time
• Change effects.type to "zoom" for Ken Burns effect
• Add your own image URLs or local file paths

Using in Your Web Application

For more control, use Liveposter as a library in your HTML:

<!DOCTYPE html>
<html>
  <head>
    <link
      rel="stylesheet"
      href="node_modules/liveposter/dist/animator.css"
    />
  </head>
  <body>
    <div id="slideshow"></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" },
        ],
      };

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

      // Control the slideshow
      // animator.pause();
      // animator.resume();
      // animator.next();
      // animator.previous();
    </script>
  </body>
</html>

Next Steps

Now that you have Liveposter running, explore more advanced features:

• Animation Modes - Learn about all available animation modes (slideshow, pan, zoom, lenticular, parallax)
• Overlays - Add visual overlays to enhance your animations
• Effects - Understand available transition effects
• Poster Spec Reference - Complete configuration schema and options
• Kiosk Mode - Deploy fullscreen displays for digital signage

Available Animation Modes

Liveposter supports multiple animation modes:

• hardcut-slideshow: Instant cuts between images
• diaporama: Smooth crossfade transitions (classic slideshow)
• pan-slideshow: Continuous panning across wide images
• zoom-slideshow: Ken Burns style zoom effect
• lenticular: Input-driven image switching (mouse/tilt)
• parallax-layers: Multiple layers with depth effect

See the Animation Modes guide for detailed examples of each mode.

Need Help?

• Check out the GitHub repository
• Report issues on GitHub Issues
• View the npm package