|
| 1 | +# LottieWeb Component Documentation |
| 2 | + |
| 3 | +The `LottieWeb` component is a lightweight Lottie animation player that supports compressed animation data (zlib format). |
| 4 | + |
| 5 | +## Installation |
| 6 | + |
| 7 | +### Dependencies |
| 8 | + |
| 9 | +Before using the component, ensure the following packages are installed in your project: |
| 10 | + |
| 11 | +- `fflate` (for decompression of zlib-compressed data) |
| 12 | +- `lottie-web` |
| 13 | + |
| 14 | +You can install these dependencies via npm or yarn: |
| 15 | + |
| 16 | +```bash |
| 17 | +npm install fflate lottie-web |
| 18 | +# or |
| 19 | +yarn add fflate lottie-web |
| 20 | +``` |
| 21 | + |
| 22 | +## Usage |
| 23 | + |
| 24 | +### Importing the Component |
| 25 | + |
| 26 | +```tsx |
| 27 | +import LottieWeb from './LottieWeb'; |
| 28 | +``` |
| 29 | + |
| 30 | +### Props |
| 31 | + |
| 32 | +The `LottieWeb` component accepts the following props: |
| 33 | + |
| 34 | +| Prop | Type | Default | Description | |
| 35 | +|----------------|-------------|-----------|----------------------------------------------------------------| |
| 36 | +| `animationData`| `Uint8Array`| Required | Compressed animation data in zlib format. | |
| 37 | +| `loop` | `boolean` | `true` | Determines whether the animation should loop. | |
| 38 | +| `autoplay` | `boolean` | `true` | Determines whether the animation should autoplay. | |
| 39 | +| `size` | `number` | `100` | The width and height of the animation container in pixels. | |
| 40 | + |
| 41 | +### Example |
| 42 | + |
| 43 | +Here is an example of how to use the `LottieWeb` component: |
| 44 | + |
| 45 | +```tsx |
| 46 | +import React from 'react'; |
| 47 | +import LottieWeb from './LottieWeb'; |
| 48 | +import MyBestZLottie from "myBestZlottie.zlottie" |
| 49 | + |
| 50 | +const App = () => { |
| 51 | + return ( |
| 52 | + <div> |
| 53 | + <h1>Lottie Animation Example</h1> |
| 54 | + <LottieWeb |
| 55 | + animationData={MyBestZLottie} |
| 56 | + loop={true} |
| 57 | + autoplay={true} |
| 58 | + size={200} |
| 59 | + /> |
| 60 | + </div> |
| 61 | + ); |
| 62 | +}; |
| 63 | + |
| 64 | +export default App; |
| 65 | +``` |
| 66 | + |
| 67 | +### Parse **.zlottie** to Uint8Array |
| 68 | +In the component, you will see that I am passing a `Uint8Array`. To accept '.zlottie' in animationData, you need to get it in string format, download it, and format it in `Uint8Array`. Here is the code that has been tested in projects! |
| 69 | +```tsx |
| 70 | +const response = await fetch(props.animationData) |
| 71 | +const arrayBuffer = await response.arrayBuffer() |
| 72 | +const compressedData = new Uint8Array(arrayBuffer) |
| 73 | +``` |
| 74 | +There will be a hint in the `LottieWeb` code where to put it. |
| 75 | + |
| 76 | +The `compressedData` will already contain what needs to be passed on to be decompressed into `fflate`! I hope it wasn't difficult! |
| 77 | + |
| 78 | +> Alternatively, you can throw this in every place where you use `lottie`, and then leave the `Uint8Array` type in `animationData`. But why ? |
| 79 | +
|
| 80 | +### Decompression Notes |
| 81 | + |
| 82 | +The `LottieWeb` component internally decompresses the provided `Uint8Array` animation data using the `fflate` library. Ensure that your animation data is correctly compressed using zlib before passing it to the component. |
| 83 | + |
| 84 | +## Component Structure |
| 85 | + |
| 86 | +The `LottieWeb` component uses the `lottie-web` library to render animations. The animation is rendered into a `div` container referenced by the `refContainer` variable. The component supports clean-up using the `useEffect` hook to destroy the animation when the component is unmounted. |
| 87 | + |
| 88 | +### Key Features |
| 89 | + |
| 90 | +- Supports zlib-compressed animation data. |
| 91 | +- Optimized for lightweight rendering with the `lottie_light` player. |
| 92 | +- Customizable playback behavior with `loop` and `autoplay` options. |
| 93 | +- Adjustable container size with the `size` prop. |
| 94 | + |
| 95 | +## Styling |
| 96 | + |
| 97 | +To style the animation container, you can use the `.LottieWeb` CSS class. The default inline styles control the width and height based on the `size` prop. |
| 98 | + |
| 99 | +```sass |
| 100 | +.LottieWeb |
| 101 | + display: inline-block |
| 102 | + overflow: hidden |
| 103 | +``` |
| 104 | + |
| 105 | +## Troubleshooting |
| 106 | + |
| 107 | +1. **Animation not displaying**: |
| 108 | + - Ensure the `animationData` prop contains valid zlib-compressed data. |
| 109 | + - Check your browser's developer console for errors. |
| 110 | + |
| 111 | +2. **Animation is static**: |
| 112 | + - Verify the `autoplay` prop is set to `true`. |
| 113 | + - Ensure the `loop` prop is correctly configured. |
| 114 | + |
| 115 | +## Contributing |
| 116 | + |
| 117 | +Feel free to contribute to the `LottieWeb` component by improving its functionality or fixing issues. For any suggestions or issues, open a GitHub pull request or issue in the repository. |
0 commit comments