Getting Started

What is dotLottie-JS

dotLottie-js serves as the primary library for creating and abstracting dotLotties.

Installation

  1. Install using your favorite package manager
npm i @dotlottie/dotlottie-js
yarn install @dotlottie/dotlottie-js
pnpm add @dotlottie/dotlottie-js

Creating a dotLottie using the library

import { DotLottie } from '@dotlottie/dotlottie-js';
// If running on Node
//import { DotLottie } from '@dotlottie/dotlottie-js/node';
import like_animation from './like.json';


const dotLottie = new DotLottie();


await dotLottie
        .setAuthor('LottieFiles')
        .setVersion('1.0')
        .addAnimation({
          id: 'like_animation',
          data: like_animation,
          loop: true,
          autoplay: true
        })
        .addAnimation({
          id: 'cat_animation',
          url: 'https://my_cat_animation.json',
          loop: true,
          autoplay: false
        })
        .build()
        .then((value) => {
          value.download('my_animation.lottie');
        });

Managing the manifest.json

The manifest file allows the player to know what animations are contained inside it, how to play them and more. All of these settings are customizable by interacting with the DotLottie object and the LottieAnimations contained inside it.

Usage

React

For a browser environment we need to install dotlottie-js.

Run:

pnpm install @dotlottie/dotlottie-js

Exemple code:

import { DotLottie } from '@dotlottie/dotlottie-js';


function App() {
  useEffect(() => {
    const createDotLottie = async () => {
      const dotlottie = new DotLottie();


      await dotlottie
        .setAuthor('Joe')
        .setVersion('1.0')
        .addAnimation({
          id: 'animation_1',
          url: 'https://x.json',
          autoplay: true,
        }).addAnimation({
          id: 'animation_2',
          url: 'https://x.json',
          autoplay: true,
        })
        .build()
        .then((value) => {
          value.download('animation.lottie');
        });
    }


    createDotLottie();
  }, [])


  return (
    <div className="App">
      ...
    </div>
  )
}

Next.js

Server side with getServerSideProps

When used with getServerSideProps, we must return a serializable object. With this restriction, one use case for getServerSideProps could be to create a dotLottie from a URL, extract an animation from it and pass it to the frontend.

Run:

pnpm install @dotlottie/dotlottie-js

Code:

import { DotLottie } from '@dotlottie/dotlottie-js/node'


export async function getServerSideProps(): Promise<Record<string, unknown>> {
  const dotlottie = new DotLottie();


  dotlottie = await dotlottie.fromURL('https://x.lottie');


  let dotLottieJson = await dotlottie.getAnimation('...');


  if (dotLottieJson)
    dotLottieJson = await dotLottieJson.toJSON();


  return {
    props: { dotLottieJson }
  }
}


export default function Home({ dotLottieJson }) {
  useEffect(() => {
  // Use the animation data however you like
    console.log(dotLottieJson)
  }, [dotLottieJson])




  return (
    <>
      ...
    </>
  )
}

Server side

dotlottie-js can be used in APIs to return .lottie Buffers.

Run:

pnpm install @dotlottie/dotlottie-js

Code:

import { DotLottie } from '@dotlottie/dotlottie-js/node';
import type { NextApiRequest, NextApiResponse } from 'next';


interface Data {
  dotLottie: Buffer | null;
}


export default async function handler(req: NextApiRequest, res: NextApiResponse<Data>) {
  const dotLottie = new DotLottie();
  let dotLottieAsBuffer = null;


  await dotLottie
    .setAuthor('Joe')
    .setVersion('1.0')
    .addAnimation({
      id: 'animation_1',
      url: 'x.json',
      autoplay: true,
    })
    .addAnimation({
      id: 'animation_2',
      url: 'x.json',
      autoplay: true,
    })
    .build()
    .then(async (value) => {
      dotLottieAsBuffer = await value.toArrayBuffer();


      res.end(Buffer.from(dotLottieAsBuffer));
    });
}

Example code taken from an apps/next/src/pages/api/create-dotlottie.ts

Client side

Run:

pnpm install @dotlottie/dotlottie-js

Code:

import { DotLottie } from '@dotlottie/dotlottie-js'


export default function Home() {


  const createDotLottie = async (): Promise<void> => {
    const dotlottie = new DotLottie();


    await dotlottie
      .setAuthor('Joe')
      .setVersion('1.0')
      .addAnimation({
        id: 'animation_1',
        url: 'x.json',
        autoplay: true,
      }).addAnimation({
        id: 'animation_2',
        url: 'x.json',
        autoplay: true,
      })
      .build()
      .then((value) => {
        value.download('animation.lottie');
      });
  }




  return (
    <>
      <button onClick={ async (): void => { await createDotLottie() }}>Download dotLottie!</button>
    </>
  )
}

Vue

For a browser environment we need to install dotlottie-js.

Run:

pnpm install @dotlottie/dotlottie-js

Example code:

<template>
...
</template>


<script>
import { DotLottie } from "@dotlottie/dotlottie-js";
import { onMounted } from "vue";


onMounted(() => {
  const createDotLottie = async () => {
    const dotlottie = new DotLottie();


    await dotlottie
      .setAuthor("Joe")
      .setVersion("1.0")
      .addAnimation({
        id: "animation_1",
        url: "x.json",
        autoplay: true,
      })
      .addAnimation({
        id: "animation_2",
        url: "x.json",
        autoplay: true,
      })
      .build()
      .then((value) => {
        value.download("animation.lottie");
      });
  };


  createDotLottie();
});


</script>

Nuxt 3

Run:

pnpm install @dotlottie/dotlottie-js

Example code:

<template>
  <div>
    <button @click="createDotLottie()">Create a dotLottie</button>
  </div>
</template>


<script lang="ts">
import { DotLottie } from '@dotlottie/dotlottie-js';


export default {
  methods: {
    createDotLottie() {
      const dotlottie = new DotLottie();


      dotlottie
        .setAuthor("Joe")
        .setVersion("1.0")
        .addAnimation({
          id: "animation_1",
          url: "https://x.json",
          autoplay: true,
        })
        .addAnimation({
          id: "animation_2",
          url: "https://x.json",
          autoplay: true,
        })
        .build()
        .then((value) => {
          value.download("animation.lottie");
        });
    },
  },


  ...
};
</script>

Playing dotLotties

Playing a dotLottie on the web

Please use the dotlottie web player: https://github.com/dotlottie/player-component

Playing a dotLottie on Android

dotLottie is supported in the lottie-android player.

Playing a dotLottie on iOS

dotLottie is supported in the lottie-ios player.

Development

Development work requires Nodejs and Pnpm.

Guidelines

  • Use defensive programming techniques: Ensure type and range of input values, cast values to native representation whenever possible, etc.
  • Refrain from using external dependencies: Discuss before adding a dependency. Check with Bundlephobia for package size and dependencies when choosing one.
  • Use code formatting in the IDE using the given eslint+prettier configs.
  • Write tests to cover all functions and code branches with valid and invalid values.

Setting up

git clone https://github.com/LottieFiles/dotlottie-js


cd dotlottie-js


pnpm install

Running test suite

pnpm run test

Building

pnpm run build