Lottie animations

This guide explains how to add Lottie animations to your custom Crane sections using the same pattern as vape_template/cover-section section template.

Overview

The pattern has three parts:

1. The animation JSON file — placed in the section's assets/ folder.
2. The useLottieAnimationLocal composable — handles lazy-loading of both the library and the animation data, and manages the animation lifecycle.
3. A client/server component split — the actual animation lives in a client-only component; the server counterpart renders an empty placeholder to avoid SSR mismatches.

1. Add dependency

lottie-web must be listed as a direct dependency in your theme's package.json:

"dependencies": {
  "lottie-web": "^5.13.0"
}

2. Place animation file

Put your Lottie JSON file inside the section's assets/ folder:

sections/
  my-section/
    assets/
      my-animation.json   ← here

The animation file can be exported from After Effects (via Bodymovin) or any other Lottie-compatible tool.

3. Add composable file

Create a new file and put it in your project like this: sections/my-section/utils/use-lottie-animation-local.ts:

import type { AnimationItem } from 'lottie-web';
import { ref, onMounted, onUnmounted, watch, type ComputedRef } from 'vue';

const IDLE_FALLBACK_DELAY_MS = 200;
const IDLE_TIMEOUT_MS = 2000;

const scheduleIdle = (fn: () => void): void => {
  if (typeof window === 'undefined') return;
  if ('requestIdleCallback' in window) {
    window.requestIdleCallback(fn, { timeout: IDLE_TIMEOUT_MS });
  } else {
    setTimeout(fn, IDLE_FALLBACK_DELAY_MS);
  }
};

export const useLottieAnimationLocal = (
  loadAnimationData: () => Promise<object>,
  showAnimation: ComputedRef<boolean>,
) => {
  const lottieContainer = ref<HTMLElement>();
  const lottieAnimationInitialized = ref(false);
  let lottieInstance: AnimationItem | null = null;

  const initializeLottieAnimation = async () => {
    if (lottieContainer.value && !lottieAnimationInitialized.value) {
      try {
        const [{ default: lottie }, animationData] = await Promise.all([
          import('lottie-web'),
          loadAnimationData(),
        ]);

        if (!lottieContainer.value) return;

        lottieInstance = lottie.loadAnimation({
          container: lottieContainer.value,
          renderer: 'svg',
          loop: true,
          autoplay: true,
          animationData,
          rendererSettings: {
            preserveAspectRatio: 'xMidYMid slice',
          },
        });

        lottieAnimationInitialized.value = true;
      } catch (error) {
        if (process.env.NODE_ENV === 'development') {
          console.warn('Failed to initialize Lottie animation:', error);
        }
      }
    }
  };

  watch(showAnimation, (newValue) => {
    if (newValue && !lottieAnimationInitialized.value) {
      scheduleIdle(initializeLottieAnimation);
    }
  });

  onMounted(() => {
    if (showAnimation.value) {
      scheduleIdle(initializeLottieAnimation);
    }
  });

  onUnmounted(() => {
    lottieInstance?.destroy();
  });

  return { lottieContainer };
};

Notes:

• Why requestIdleCallback? Loading and decoding a Lottie JSON (which can be 1–2 MB) is expensive. Deferring it to idle time prevents it from competing with the hero image for bandwidth and main-thread time during LCP.
• Why dynamic import('lottie-web')? The library is only needed on the client and only when the animation is actually shown. Dynamic import keeps it out of the initial JS bundle.

4. Add sectionAssetUrl helper

Similarly, create a new file here: shared/utils/section-asset-url.ts:

export function sectionAssetUrl(filename: string, moduleUrl: string): string {
  let base = moduleUrl;
  const clientIdx = base.lastIndexOf('/client/');
  if (clientIdx !== -1) {
    base = base.slice(0, clientIdx);
  }
  base = base.replace(/\/js\/main$/, '');
  return `${base}/assets/${encodeURIComponent(filename)}`;
}

Then import and use it in any component that needs to fetch a section asset:

import { sectionAssetUrl } from '../../../shared/utils/section-asset-url';

async function loadAnimationData() {
  const url = sectionAssetUrl('my-animation.json', import.meta.url);
  const response = await fetch(url);
  return response.json();
}

Important: always pass import.meta.url from the calling component file, not from inside a shared helper. Rollup can move shared chunks to a different path, so reading import.meta.url inside the helper would resolve to the wrong location.

5. Add client and server components

Create a new file for the client component in sections/my-section/components/AnimatedBackground.vue:

<template>
  <div v-show="show" class="my-section__animated-bg">
    <div ref="lottieContainer" class="my-section__lottie-animation"></div>
  </div>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { sectionAssetUrl } from '../../../shared/utils/section-asset-url';
import { useLottieAnimationLocal } from '../utils/use-lottie-animation-local';

interface Props {
  show: boolean;
}

const props = defineProps<Props>();

async function loadAnimationData() {
  const url = sectionAssetUrl('my-animation.json', import.meta.url);
  const response = await fetch(url);
  return response.json();
}

const showAnimation = computed(() => props.show);
const { lottieContainer } = useLottieAnimationLocal(loadAnimationData, showAnimation);
</script>

And a file for the server component in: sections/my-section/components/AnimatedBackgroundServer.vue.

Note: The server component is a no-op placeholder. It must exist to prevent SSR hydration mismatches — the client component must not render on the server.

<template>
  <div v-show="show" class="my-section__animated-bg">
    <div class="my-section__lottie-animation"></div>
  </div>
</template>

<script setup lang="ts">
interface Props {
  show: boolean;
}
defineProps<Props>();
</script>

You also need to import new components in your client/server section files:

<!-- MyClient.vue -->
<script setup lang="ts">
import AnimatedBackground from './components/AnimatedBackground.vue';
</script>

<!-- MyServer.vue -->
<script setup lang="ts">
import AnimatedBackground from './components/AnimatedBackgroundServer.vue';
</script>

Both use <AnimatedBackground :show="showAnimation" /> in the template.

6. Add a CMS toggle (optional)

If you want the end user to be able to enable/disable the animation in the theme editor, add a TOGGLE setting in your section's content file sections/my-section/settings/content.ts:

showAnimatedBackground: {
  type: 'TOGGLE',
  label: '$label.show_animated_background.label',
  description: '$label.show_animated_background.description',
  defaults: {
    enabled: true,
  },
},

Then derive a computed prop from it and pass it to the component:

const showAnimation = computed(() => settings.showAnimatedBackground.enabled);