Lottie Animation

When to use

The Lottie component can render Lottie animations conveniently and simply, and provides a way to obtain global Lottie and animation instances to meet a wider range of configuration needs. lottie-web is used internally to render Lottie animations. Compared to using lottie-web directly, use the Semi Lottie component

• No need to worry about the creation and destruction of animation containers
• No need to worry about the life cycle of the animation itself

• Easier to use with Vue projects

Demos

How to import

<script setup lang="ts">
    import { Lottie } from '@fibrous/semi-ui-vue';
</script>

Basic Usage

When the Lottie animation resource JSON is on CDN

Pass path=your lottie json URL to the params props

<script setup lang="ts">
    import { Lottie } from '@fibrous/semi-ui-vue';

    const jsonURL = '/assets/root-web-sites/lottie_demo.json';
    const params = { path: jsonURL };
</script>

<template>
    <div>
        <Lottie height="300px" :params="params" width="300px" />
    </div>
</template>

When Lottie animation resource JSON needs to be packaged into the website code

Pass animationData=your lottie json object into the params props (the Demo request JSON below is only for demonstration. In actual projects, json should be manually imported instead of obtained through network requests, so that JSON animation resources can be packaged into the website code)

<script setup lang="ts">
    import { computed, onMounted, shallowRef } from 'vue';
    import { Lottie } from '@fibrous/semi-ui-vue';

    const jsonURL = '/assets/root-web-sites/lottie_demo.json';

    // large animation data is held in a shallowRef so it is not made deeply reactive
    const data = shallowRef<object | string>('');
    // params reloads the animation when it is replaced, so it is derived from the data instead of mutated
    const params = computed(() => ({ animationData: data.value }));

    onMounted(() => {
        void fetch(jsonURL)
            .then((resp) => resp.json())
            .then((json: object) => {
                data.value = json;
            });
    });
</script>

<template>
    <div>
        <Lottie height="300px" :params="params" width="300px" />
    </div>
</template>

Params Other common parameters

params will be passed to lottie.loadAnimation of lottie-web by the component. Please refer to lottie-web documentation

Common parameters

//params
{
  container: element, // Rendering container, if not passed, Semi Lottie component will automatically configure and generate
  renderer: 'svg', // Rendering mode, default SVG
  loop: true, // Whether to open loop, default true
  autoplay: true, // Whether to play automatically, default true, when set to false, you need to manually play through the play method on the animation instance
  path: 'data.json' // URL path of animation JSON file (mutually exclusive with animationData)
  animationData: {/*...*/} // JSON object of animation (mutually exclusive with animationData)
  /*...*/
}

Get the current animation instance

Listen to the @getAnimationInstance event to get the animation instance of the currently playing animation. The instance contains many methods for adjusting various parameters of the animation, such as playing and pausing, getting the current frame number, adjusting the playback speed, etc. The event is emitted once per animation created, including every reload, and its payload is an AnimationItem, never null.

For more information about the methods contained in the animation instance, please refer to the lottie-web documentation

<script setup lang="ts">
    import { Lottie, type LottieAnimation } from '@fibrous/semi-ui-vue';

    const jsonURL = '/assets/root-web-sites/lottie_demo.json';
    const params = { path: jsonURL };

    const onAnimation = (animation: LottieAnimation) => {
        console.log(animation);
    };
</script>

<template>
    <div>
        <Lottie height="300px" :params="params" width="300px" @getAnimationInstance="onAnimation" />
    </div>
</template>

Get global Lottie

Listen to the @getLottie event to get global lottie, or use the static method Lottie.getLottie on the Semi Lottie component to get global lottie

lottie-web is large, so Semi loads it on demand when an animation needs to be created. The getLottie event is emitted once it has loaded and the animation is created, once per mount. The static method Lottie.getLottie() is asynchronous and returns a Promise that resolves to lottie (use await or .then). The component renders no animation until lottie-web has loaded, and if it unmounts before that, no animation is created.

For more information about the methods on the global lottie, please refer to the lottie-web documentation

<script setup lang="ts">
    import { onMounted } from 'vue';
    import { Lottie, type LottieModule } from '@fibrous/semi-ui-vue';

    const jsonURL = '/assets/root-web-sites/lottie_demo.json';
    const params = { path: jsonURL };

    const onLottie = (lottie: LottieModule) => {
        console.log('lottie', lottie);
    };

    onMounted(() => {
        void Lottie.getLottie().then((lottie) => console.log('lottie', lottie));
    });
</script>

<template>
    <div>
        <Lottie height="300px" :params="params" width="300px" @getLottie="onLottie" />
    </div>
</template>

API

Props

Events

Slots

Exposes

class, style and native attributes land on the container element through attrs. params reloads by reference change plus a deep comparison: passing a new literal on every parent render does not reload, replacing it with different content does, and mutating params in place does not. Hold large animation data in a shallowRef or markRaw; the component passes the raw object to lottie-web. When params.container is set, the component renders only a comment node, $el is that comment, and attrs are dropped.

Static methods

Accessibility

• An animation with aria-label or aria-labelledby is a named image, and its container gets role="img"; an animation without a name is decoration, and its container gets aria-hidden="true". A role or aria-* you pass wins
• With prefers-reduced-motion: reduce set in the system, the animation does not autoplay, and it pauses or plays as the setting changes while running; an explicit params.autoplay takes precedence

Design Tokens