Blottie

Lottie component for Vue 3 / Nuxt 3

Blottie is the verb blottir in french meaning snuggle (yes I was looking for a word to respect the Vue tradition).

Features

• 🔥 Integrated to VueJS with all Lottie loadAnimations options and events
• 😎 Available through Blottie component or useBlottie composable.
• 🚀 Load automatically the best renderer: you can't be lighter
• 📠 Fully typed
• ✨ Expose lottie player/animation for more control and customization

Installation

1npm i -D blottie
2
3# yarn
4yarn add -D blottie
5
6# pnpm
7pnpm add -D blottie
8
9#bun
10bun add -D blottie

Usage

Component

1<script setup lang="ts">
2import type { AnimationItem } from 'lottie-web'
3import { Blottie, type BlottieExpose } from 'blottie'
4
5const blottie = ref<BlottieExpose>()
6
7function onFrame(anim?: AnimationItem) {
8  frame.value = Math.round(anim ? anim.currentFrame : 0)
9}
10function onReady(anim?: AnimationItem) {
11  anim?.play()
12}
13</script>
14
15<template>
16  <Blottie
17    ref="blottie"
18    :lottie="{
19      loop: true,
20      renderer: 'svg',
21      path: '/my-lottie-anim.json',
22    }"
23    @ready="onReady"
24    @enter-frame="onFrame"
25  />
26</template>

It is recommended to use the renderer option to use the correct version of Lottie to reduce the size of Lottie. If you don't use the renderer prop, it will use the default LottiePlayer which can be a little heavier in size. The lighter option provided by Lottie is the light version which is loaded when you set the svg renderer.

Check the demo folder for examples of usage.

Props

The Blottie component accepts all loadAnimation options through lottie prop. You can pass a Lottie Animation JSON via the path option (relative or absolute link) or directly by importing the json file as an object in the animationData option.

By default, Blottie will load the lighter version (light) of Lottie for the renderer you choose. If necessary, you can enforce the lottie player with the player option (inside the lottie prop) : canvas_worker, canvas, light_canvas, html, light_html, light, svg, worker or default.

1<script lang="ts" setup>
2import { Blottie } from 'blottie'
3</script>
4
5<template>
6  <Blottie
7    :lottie="{
8      player: 'svg',
9      renderer: 'svg',
10      path: '/my-lottie-anim.json',
11    }"
12  />
13</template>

If needed, you can access the lottie player before the lottie loadAnimation method. You can use the before-init prop allowing you to pass an asynchrone callback with the player as an argument (check the example below).

This is necessary for allowing to use setLocationHref to fix Safari issue.

1<script setup lang="ts">
2import type { LottiePlayer } from 'lottie-web'
3import { Blottie } from 'blottie'
4
5async function beforeInit(player: LottiePlayer) {
6  console.log(player)
7}
8</script>
9
10<template>
11  <div>
12    <Blottie
13      class="animation"
14      :before-init="beforeInit"
15      :lottie="{
16        path: 'vue-js.json',
17        autoplay: true,
18      }"
19    />
20  </div>
21</template>

An additional prop container-tag is available to change the default div tag container.

1<script lang="ts" setup>
2import { Blottie } from 'blottie'
3</script>
4
5<template>
6  <Blottie
7    container-tag="main"
8    :lottie="{
9      renderer: 'svg',
10      path: '/my-lottie-anim.json',
11    }"
12  />
13</template>

Events

The Blottie component exposes all lottie events. On each events, you can access to anim allowing you to control your animation, lottie to control the player and the HTML container.

1import type { AnimationItem, LottiePlayer } from 'lottie-web'
2
3function onFrame(anim?: AnimationItem, lottie?: LottiePlayer, container?: HTMLElement) {
4  frame.value = Math.round(anim ? anim.currentFrame : 0)
5}

Expose LottiePlayer / Anim / Container

You can access to all the Blottie data (lottie player, animation and container) exposed using ref attribute on the Blottie component. You can do a custom player for example.

1<script setup lang="ts">
2import type { AnimationItem, LottiePlayer } from 'lottie-web'
3import { ref } from 'vue'
4import { Blottie, type BlottieExpose } from 'blottie'
5
6const blottie = ref<BlottieExpose>()
7</script>
8
9<template>
10  <div>
11    <Blottie
12      ref="blottie"
13      class="animation"
14      :lottie="{
15        animationData: 'animationData',
16        renderer: 'canvas',
17      }"
18    />
19    <div v-if="blottie && blottie.anim" class="controls">
20      <progress
21        :value="blottie.anim.currentFrame"
22        :max="blottie.anim.totalFrames"
23      />
24      <button @click="blottie?.anim.play()">
25        Play
26      </button>
27      <button @click="blottie?.anim.pause()">
28        Pause
29      </button>
30      <button @click="blottie?.anim.stop()">
31        Stop
32      </button>
33      <button
34        @click="
35          blottie?.anim.setDirection(
36            blottie?.anim.playDirection === -1 ? 1 : -1,
37          )
38        "
39      >
40        Reverse
41      </button>
42    </div>
43  </div>
44</template>

Slot

You can use the slot loading to insert content inside the container to wait the display like a temporary fallback.

1<script lang="ts" setup>
2import { Blottie } from 'blottie'
3</script>
4
5<template>
6  <Blottie
7    :lottie="{
8      autoplay: true,
9      loop: true,
10      path: '/my-lottie-anim.json',
11    }"
12  >
13    <template #loading>
14      Loading...
15    </template>
16  </Blottie>
17</template>

Composable

Since 2.0, you can use the composable useBlottie. This allowing you full control to create a custom component if you need it.

The first argument is a template ref. The second argument is an object accepting all loadAnimation options.

1<script setup lang="ts">
2import { useBlottie } from 'blottie'
3const el = ref<HTMLElement | null>(null)
4const { lottie, anim } = useBlottie(el, {
5  player: 'svg',
6  renderer: 'svg',
7  path: '/my-lottie-anim.json',
8})
9</script>
10
11<template>
12  <div>
13    <div ref="el" class="blottie" />
14    <button @click="lottie.play()">
15      Play
16    </button>
17  </div>
18</template>

Migration from 1.0 to 2.0

All Lottie options are now move into lottie attribute to use typings from lottie (and not a version provided by Blottie).

For example, if you have this

1<template>
2  <Blottie
3    class="animation"
4    path="https://assets6.lottiefiles.com/packages/lf20_bXGMKilbSf.json"
5    :loop="true"
6    container-tag="main"
7    @ready="onReady"
8  >
9    <template #loading>
10      Loading...
11    </template>
12  </Blottie>
13</template>

This will be change to this

1<template>
2  <Blottie
3    class="animation"
4    :lottie="{
5      loop: true,
6      path: 'https://assets6.lottiefiles.com/packages/lf20_bXGMKilbSf.json',
7    }"
8    container-tag="main"
9    @ready="onReady"
10    @loop-complete="onLoop"
11  >
12    <template #loading>
13      Loading...
14    </template>
15  </Blottie>
16</template>

Why?

Lottie is a great library allowing designer to make an animation on after effects and export it to the web.

If you don't know what is lottie, check the official website.

But the integration is not easy on VueJS and I needed one for a company project. So I was looking for a VueJS 3 library.

LottieFiles provides a player named lottie-player but it was not light enought for my need and It was not customizable enough : if you don't find suitable for you need, make your own component 🤓

👨‍💼 Licence

MIT