Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/applelo/blottie

Lottie component for VueJS 3 / Nuxt 3
https://github.com/applelo/blottie

animation lottie lottie-web nuxt nuxt3 vue vue3 vuejs

Last synced: 3 months ago
JSON representation

Lottie component for VueJS 3 / Nuxt 3

Awesome Lists containing this project

README 

        
[![npm](https://img.shields.io/npm/v/blottie)](https://www.npmjs.com/package/blottie) [![node-current](https://img.shields.io/node/v/blottie)](https://nodejs.org/) [![Blottie](https://img.shields.io/endpoint?url=https://cloud.cypress.io/badge/simple/k3qz2d/main&style=flat&logo=cypress)](https://cloud.cypress.io/projects/k3qz2d/runs)



# 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](https://github.com/airbnb/lottie-web#other-loading-options) and [events](https://github.com/airbnb/lottie-web#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



```shell

npm i -D blottie



# yarn

yarn add -D blottie



# pnpm

pnpm add -D blottie



#bun

bun add -D blottie

```



## Usage



### Component



```vue



import type { AnimationItem } from 'lottie-web'

import { Blottie, type BlottieExpose } from 'blottie'



const blottie = ref<BlottieExpose>()



function onFrame(anim?: AnimationItem) {

  frame.value = Math.round(anim ? anim.currentFrame : 0)

}

function onReady(anim?: AnimationItem) {

  anim?.play()

}



  



```



**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](https://github.com/Applelo/blottie/blob/main/demo/src/App.vue) folder for examples of usage.



### Props



The Blottie component accepts all [loadAnimation options](https://github.com/airbnb/lottie-web#other-loading-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`.



```vue



import { Blottie } from 'blottie'



  



```



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](https://github.com/airbnb/lottie-web#issues).



```vue



import type { LottiePlayer } from 'lottie-web'

import { Blottie } from 'blottie'



async function beforeInit(player: LottiePlayer) {

  console.log(player)

}



  


    

  



```



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



```vue



import { Blottie } from 'blottie'



  



```



### Events



The Blottie component exposes all [lottie events](https://github.com/airbnb/lottie-web#events). On each events, you can access to `anim` allowing you to control your animation, `lottie` to control the player and the HTML `container`.



```ts

import type { AnimationItem, LottiePlayer } from 'lottie-web'



function onFrame(anim?: AnimationItem, lottie?: LottiePlayer, container?: HTMLElement) {

  frame.value = Math.round(anim ? anim.currentFrame : 0)

}

```



### 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.



```vue



import type { AnimationItem, LottiePlayer } from 'lottie-web'

import { ref } from 'vue'

import { Blottie, type BlottieExpose } from 'blottie'



const blottie = ref<BlottieExpose>()



  


    

    


      

      

        Play

      

      

        Pause

      

      

        Stop

      

      

        Reverse

      

    


  



```



### Slot



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



```vue



import { Blottie } from 'blottie'



  

    

      Loading...

    

  



```



### 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](https://vuejs.org/guide/essentials/template-refs.html#template-refs).

The second argument is an object accepting all [loadAnimation options](https://github.com/airbnb/lottie-web#other-loading-options).



```vue



import { useBlottie } from 'blottie'

const el = ref<HTMLElement | null>(null)

const { lottie, anim } = useBlottie(el, {

  player: 'svg',

  renderer: 'svg',

  path: '/my-lottie-anim.json',

})



  


    


    

      Play

    

  



```



## 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

```vue



  

    

      Loading...

    

  



```



This will be change to this

```vue



  

    

      Loading...

    

  



```



## 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](https://airbnb.io/lottie/#/).



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](https://github.com/LottieFiles/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