DEV Community

Fazal Shah
Fazal Shah

Posted on

Testing and Documenting Lottie Animations in Storybook

Lottie animations are hard to review in code review. Storybook fixes that — here's how to document, control, and visually test Lottie components.

Why Storybook for Lottie?

Animation components have state that's invisible in a code diff:

  • Does it loop?
  • Does it play at the right speed?
  • Do the colors match the brand?
  • Does it stop when it should?

Storybook makes all of this visible to designers and reviewers without running the full app.

Basic Lottie Story 

// LottiePlayer.stories.jsx
import { DotLottieReact } from '@lottiefiles/dotlottie-react';
import loadingAnim from './assets/loading.lottie';
import successAnim from './assets/success.lottie';

export default {
  title: 'Animations/LottiePlayer',
  component: DotLottieReact,
  argTypes: {
    loop: { control: 'boolean' },
    autoplay: { control: 'boolean' },
  },
};

export const Loading = {
  args: {
    src: loadingAnim,
    loop: true,
    autoplay: true,
    style: { width: 120, height: 120 },
  },
};

export const Success = {
  args: {
    src: successAnim,
    loop: false,
    autoplay: true,
    style: { width: 120, height: 120 },
  },
};
Enter fullscreen mode Exit fullscreen mode

Now any team member can open Storybook, see both animations playing, and toggle loop/autoplay in the Controls panel.

Wrapping in a Component Story

For a real AnimatedButton component:

// AnimatedButton.stories.jsx
import AnimatedButton from './AnimatedButton';

export default {
  title: 'Components/AnimatedButton',
  component: AnimatedButton,
};

export const Default = {};

export const Loading = {
  args: { state: 'loading' },
};

export const Success = {
  args: { state: 'success' },
};

export const Error = {
  args: { state: 'error' },
};
Enter fullscreen mode Exit fullscreen mode

This documents all animation states in one place — designers can verify each one looks correct.

Adding Controls for Speed and Direction 

export default {
  title: 'Animations/Showcase',
  argTypes: {
    speed: { control: { type: 'range', min: 0.25, max: 4, step: 0.25 } },
    loop: { control: 'boolean' },
    src: {
      control: 'select',
      options: ['loading', 'success', 'error', 'empty'],
      mapping: {
        loading: '/animations/loading.lottie',
        success: '/animations/success.lottie',
        error: '/animations/error.lottie',
        empty: '/animations/empty.lottie',
      },
    },
  },
};
Enter fullscreen mode Exit fullscreen mode

Visual Regression Testing

With Chromatic or Percy, you can catch animation regressions:

import { composeStories } from '@storybook/react';
import * as stories from './LottiePlayer.stories';

const { Loading, Success } = composeStories(stories);

test('Loading animation renders', () => {
  const { container } = render(<Loading />);
  expect(container.querySelector('canvas')).toBeInTheDocument();
});
Enter fullscreen mode Exit fullscreen mode

For true visual diff, Chromatic captures the first frame and diffs it on each deploy.

Preparing Animation Files

Before adding animations to Storybook:

  1. Preview at IconKing to confirm all states render correctly
  2. Edit colors to match your design system tokens
  3. Convert to .lottie — smaller files = faster Storybook builds

IconKing converts .json → .lottie in the browser with no account.

Summary

Storybook + Lottie = a reviewable animation library. Designers can verify their animations render correctly, engineers can document all states, and Chromatic can catch regressions automatically. Set it up once and it pays off on every PR.

Top comments (0)