{"id":17786042,"url":"https://github.com/applelo/blottie","last_synced_at":"2025-03-16T05:31:06.612Z","repository":{"id":65809690,"uuid":"588949888","full_name":"Applelo/blottie","owner":"Applelo","description":"Lottie component for VueJS 3 / Nuxt 3","archived":false,"fork":false,"pushed_at":"2024-05-03T17:36:16.000Z","size":560,"stargazers_count":13,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-12T01:01:50.385Z","etag":null,"topics":["animation","lottie","lottie-web","nuxt","nuxt3","vue","vue3","vuejs"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Applelo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-14T15:25:25.000Z","updated_at":"2025-02-28T18:42:03.000Z","dependencies_parsed_at":"2024-04-17T21:00:13.461Z","dependency_job_id":"516d9003-ca71-4f83-91c0-7bed5e8982b9","html_url":"https://github.com/Applelo/blottie","commit_stats":{"total_commits":36,"total_committers":1,"mean_commits":36.0,"dds":0.0,"last_synced_commit":"d426f7e80be6ef96c0c90a4f0d08a00805f4dfdd"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Applelo%2Fblottie","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Applelo%2Fblottie/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Applelo%2Fblottie/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Applelo%2Fblottie/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Applelo","download_url":"https://codeload.github.com/Applelo/blottie/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243830912,"owners_count":20354848,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["animation","lottie","lottie-web","nuxt","nuxt3","vue","vue3","vuejs"],"created_at":"2024-10-27T09:04:12.214Z","updated_at":"2025-03-16T05:31:05.845Z","avatar_url":"https://github.com/Applelo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"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\u0026style=flat\u0026logo=cypress)](https://cloud.cypress.io/projects/k3qz2d/runs)\n\n# Blottie\n\n\u003e Lottie component for Vue 3 / Nuxt 3\n\nBlottie is the verb `blottir` in french meaning `snuggle` (yes I was looking for a word to respect the Vue tradition).\n\n## Features\n\n- 🔥 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)\n- 😎 Available through `Blottie` component or `useBlottie` composable.\n- 🚀 Load automatically the best renderer: you can't be lighter\n- 📠 Fully typed\n- ✨ Expose lottie player/animation for more control and customization\n\n## Installation\n\n```shell\nnpm i -D blottie\n\n# yarn\nyarn add -D blottie\n\n# pnpm\npnpm add -D blottie\n\n#bun\nbun add -D blottie\n```\n\n## Usage\n\n### Component\n\n```vue\n\u003cscript setup lang=\"ts\"\u003e\nimport type { AnimationItem } from 'lottie-web'\nimport { Blottie, type BlottieExpose } from 'blottie'\n\nconst blottie = ref\u003cBlottieExpose\u003e()\n\nfunction onFrame(anim?: AnimationItem) {\n  frame.value = Math.round(anim ? anim.currentFrame : 0)\n}\nfunction onReady(anim?: AnimationItem) {\n  anim?.play()\n}\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n  \u003cBlottie\n    ref=\"blottie\"\n    :lottie=\"{\n      loop: true,\n      renderer: 'svg',\n      path: '/my-lottie-anim.json',\n    }\"\n    @ready=\"onReady\"\n    @enter-frame=\"onFrame\"\n  /\u003e\n\u003c/template\u003e\n```\n\n**It is recommended to use the renderer option to use the correct version of Lottie to reduce the size of Lottie.**\nIf 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.\n\n\u003e Check the [demo](https://github.com/Applelo/blottie/blob/main/demo/src/App.vue) folder for examples of usage.\n\n### Props\n\nThe 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.\n\nBy 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`.\n\n```vue\n\u003cscript lang=\"ts\" setup\u003e\nimport { Blottie } from 'blottie'\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n  \u003cBlottie\n    :lottie=\"{\n      player: 'svg',\n      renderer: 'svg',\n      path: '/my-lottie-anim.json',\n    }\"\n  /\u003e\n\u003c/template\u003e\n```\n\nIf 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).\n\n\u003e This is necessary for allowing to use `setLocationHref` to [fix Safari issue](https://github.com/airbnb/lottie-web#issues).\n\n```vue\n\u003cscript setup lang=\"ts\"\u003e\nimport type { LottiePlayer } from 'lottie-web'\nimport { Blottie } from 'blottie'\n\nasync function beforeInit(player: LottiePlayer) {\n  console.log(player)\n}\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n  \u003cdiv\u003e\n    \u003cBlottie\n      class=\"animation\"\n      :before-init=\"beforeInit\"\n      :lottie=\"{\n        path: 'vue-js.json',\n        autoplay: true,\n      }\"\n    /\u003e\n  \u003c/div\u003e\n\u003c/template\u003e\n```\n\nAn additional prop `container-tag` is available to change the default `div` tag container.\n\n```vue\n\u003cscript lang=\"ts\" setup\u003e\nimport { Blottie } from 'blottie'\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n  \u003cBlottie\n    container-tag=\"main\"\n    :lottie=\"{\n      renderer: 'svg',\n      path: '/my-lottie-anim.json',\n    }\"\n  /\u003e\n\u003c/template\u003e\n```\n\n### Events\n\nThe 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`.\n\n```ts\nimport type { AnimationItem, LottiePlayer } from 'lottie-web'\n\nfunction onFrame(anim?: AnimationItem, lottie?: LottiePlayer, container?: HTMLElement) {\n  frame.value = Math.round(anim ? anim.currentFrame : 0)\n}\n```\n\n### Expose LottiePlayer / Anim / Container\n\nYou 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.\n\n```vue\n\u003cscript setup lang=\"ts\"\u003e\nimport type { AnimationItem, LottiePlayer } from 'lottie-web'\nimport { ref } from 'vue'\nimport { Blottie, type BlottieExpose } from 'blottie'\n\nconst blottie = ref\u003cBlottieExpose\u003e()\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n  \u003cdiv\u003e\n    \u003cBlottie\n      ref=\"blottie\"\n      class=\"animation\"\n      :lottie=\"{\n        animationData: 'animationData',\n        renderer: 'canvas',\n      }\"\n    /\u003e\n    \u003cdiv v-if=\"blottie \u0026\u0026 blottie.anim\" class=\"controls\"\u003e\n      \u003cprogress\n        :value=\"blottie.anim.currentFrame\"\n        :max=\"blottie.anim.totalFrames\"\n      /\u003e\n      \u003cbutton @click=\"blottie?.anim.play()\"\u003e\n        Play\n      \u003c/button\u003e\n      \u003cbutton @click=\"blottie?.anim.pause()\"\u003e\n        Pause\n      \u003c/button\u003e\n      \u003cbutton @click=\"blottie?.anim.stop()\"\u003e\n        Stop\n      \u003c/button\u003e\n      \u003cbutton\n        @click=\"\n          blottie?.anim.setDirection(\n            blottie?.anim.playDirection === -1 ? 1 : -1,\n          )\n        \"\n      \u003e\n        Reverse\n      \u003c/button\u003e\n    \u003c/div\u003e\n  \u003c/div\u003e\n\u003c/template\u003e\n```\n\n### Slot\n\nYou can use the slot `loading` to insert content inside the container to wait the display like a temporary fallback.\n\n```vue\n\u003cscript lang=\"ts\" setup\u003e\nimport { Blottie } from 'blottie'\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n  \u003cBlottie\n    :lottie=\"{\n      autoplay: true,\n      loop: true,\n      path: '/my-lottie-anim.json',\n    }\"\n  \u003e\n    \u003ctemplate #loading\u003e\n      Loading...\n    \u003c/template\u003e\n  \u003c/Blottie\u003e\n\u003c/template\u003e\n```\n\n### Composable\n\nSince 2.0, you can use the composable `useBlottie`. This allowing you full control to create a custom component if  you need it.\n\nThe first argument is a [template ref](https://vuejs.org/guide/essentials/template-refs.html#template-refs).\nThe second argument is an object accepting all [loadAnimation options](https://github.com/airbnb/lottie-web#other-loading-options).\n\n```vue\n\u003cscript setup lang=\"ts\"\u003e\nimport { useBlottie } from 'blottie'\nconst el = ref\u003cHTMLElement | null\u003e(null)\nconst { lottie, anim } = useBlottie(el, {\n  player: 'svg',\n  renderer: 'svg',\n  path: '/my-lottie-anim.json',\n})\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n  \u003cdiv\u003e\n    \u003cdiv ref=\"el\" class=\"blottie\" /\u003e\n    \u003cbutton @click=\"lottie.play()\"\u003e\n      Play\n    \u003c/button\u003e\n  \u003c/div\u003e\n\u003c/template\u003e\n```\n\n## Migration from 1.0 to 2.0\n\nAll Lottie options are now move into `lottie` attribute to use typings from lottie (and not a version provided by Blottie).\n\nFor example, if you have this\n```vue\n\u003ctemplate\u003e\n  \u003cBlottie\n    class=\"animation\"\n    path=\"https://assets6.lottiefiles.com/packages/lf20_bXGMKilbSf.json\"\n    :loop=\"true\"\n    container-tag=\"main\"\n    @ready=\"onReady\"\n  \u003e\n    \u003ctemplate #loading\u003e\n      Loading...\n    \u003c/template\u003e\n  \u003c/Blottie\u003e\n\u003c/template\u003e\n```\n\nThis will be change to this\n```vue\n\u003ctemplate\u003e\n  \u003cBlottie\n    class=\"animation\"\n    :lottie=\"{\n      loop: true,\n      path: 'https://assets6.lottiefiles.com/packages/lf20_bXGMKilbSf.json',\n    }\"\n    container-tag=\"main\"\n    @ready=\"onReady\"\n    @loop-complete=\"onLoop\"\n  \u003e\n    \u003ctemplate #loading\u003e\n      Loading...\n    \u003c/template\u003e\n  \u003c/Blottie\u003e\n\u003c/template\u003e\n```\n\n## Why?\n\nLottie is a great library allowing designer to make an animation on after effects and export it to the web.\n\n\u003e If you don't know what is lottie, check the [official website](https://airbnb.io/lottie/#/).\n\nBut the integration is not easy on VueJS and I needed one for a company project. So I was looking for a VueJS 3 library.\n\nLottieFiles 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 🤓\n\n## 👨‍💼 Licence\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapplelo%2Fblottie","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapplelo%2Fblottie","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapplelo%2Fblottie/lists"}