{"id":15286218,"url":"https://github.com/giuseppelt/astro-lottie","last_synced_at":"2025-09-05T02:18:51.490Z","repository":{"id":64409116,"uuid":"571652963","full_name":"giuseppelt/astro-lottie","owner":"giuseppelt","description":"Use Lottie animations within your Astro website","archived":false,"fork":false,"pushed_at":"2024-12-18T00:27:38.000Z","size":117,"stargazers_count":47,"open_issues_count":2,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-08-09T01:43:55.602Z","etag":null,"topics":["astro","astro-component","astro-integration","lottie","lottie-animation"],"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/giuseppelt.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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":"2022-11-28T15:40:08.000Z","updated_at":"2025-08-07T18:44:23.000Z","dependencies_parsed_at":"2023-11-28T12:25:48.300Z","dependency_job_id":"cf10b54e-7a70-420d-adaa-d823766b3be4","html_url":"https://github.com/giuseppelt/astro-lottie","commit_stats":{"total_commits":28,"total_committers":3,"mean_commits":9.333333333333334,"dds":0.0714285714285714,"last_synced_commit":"176b2ea983f817cac0e99b4b92026b2b23f69ff2"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/giuseppelt/astro-lottie","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giuseppelt%2Fastro-lottie","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giuseppelt%2Fastro-lottie/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giuseppelt%2Fastro-lottie/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giuseppelt%2Fastro-lottie/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/giuseppelt","download_url":"https://codeload.github.com/giuseppelt/astro-lottie/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giuseppelt%2Fastro-lottie/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273699927,"owners_count":25152330,"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","status":"online","status_checked_at":"2025-09-05T02:00:09.113Z","response_time":402,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["astro","astro-component","astro-integration","lottie","lottie-animation"],"created_at":"2024-09-30T15:11:14.034Z","updated_at":"2025-09-05T02:18:51.457Z","avatar_url":"https://github.com/giuseppelt.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Astro Lottie\nUse [Lottie](https://github.com/airbnb/lottie-web) animations within your [Astro](https://astro.build) website.\n\n\n## Installation\n**astro-integration-lottie** requires **lottie-web** to be installed as well.\n```bash\nnpm i astro-integration-lottie lottie-web\n# or\npnpm add astro-integration-lottie lottie-web\n# or\nyarn add astro-integration-lottie lottie-web\n```\n\n## Usage\n### Integration\nRequired first step: add the integration to your `astro.config` file.\n```ts \nimport { defineConfig } from \"astro/config\";\nimport lottie from \"astro-integration-lottie\";\n\nexport default defineConfig({\n  integrations: [\n    lottie(), // \u003c-- add integration\n  ]\n});\n```\n\n### Type support\nThis integration defines the `astroLottie` global object to interact with your animations inside a page. Details on the [dedicated section](#accessing-the-lottie-player). You can have full type info of the `astroLottie` object with an environment reference.\n\nCreate an `env.d.ts` or, if you already have one, add the following line:\n```ts\n/// \u003creference types=\"astro-integration-lottie/env\" /\u003e\n```\n\n### Component\nInside your astro page or component, you can import the Lottie component. It supports props autocompletion and type checking.\n```astro\n---\nimport LottieAnimation from \"astro-integration-lottie/Lottie.astro\";\n---\n\u003cdiv class=\"container\"\u003e\n    \u003cLottieAnimation src=\"assets/animation.json\" autoplay=\"visible\" /\u003e\n\u003c/div\u003e\n```\n\n### Styling, sizing and constraints\nYou can use a parent `div` as a container to set the size and set additional styling (background, ...).\n\nYou can either use the `style` attribute or reference a css `class`.\n```html\n\u003c!-- with css class --\u003e\n\u003cdiv class=\"container\"\u003e\n    \u003cLottieAnimation src=\"assets/animation.json\" autoplay=\"visible\" /\u003e\n\u003c/div\u003e\n\n\n\u003c!-- or style --\u003e\n\u003cdiv style=\"width: 200px; height: 150px;\"\u003e\n    \u003cLottieAnimation src=\"assets/animation.json\" autoplay=\"visible\" /\u003e\n\u003c/div\u003e\n```\n\nAlso, you can use the `class` or `class:list` attribute to add custom css classes directly to the lottie container.\n\n```jsx\n\u003cLottieAnimation src=\"assets/animation.json\" autoplay=\"visible\" class=\"my-class my-other-class\" /\u003e\n\n\u003c!-- or --\u003e\n\n\u003cLottieAnimation src=\"assets/animation.json\" autoplay=\"visible\" class:list={[\"my-class\", \"my-other-class\"]} /\u003e\n```\n\n\n## How `Astro Lottie` works\n### Player loading\nThe lottie player is not bundled within your page. It's asynchronously fetched only when a page contains at least one lottie animation.\n\nThis package allows to load two players:\n- `light`: small player with only svg rendering\n- `full`: all featured player, with all capabilities\n\nYou can read more about lottie players in the [Lottie repository](https://github.com/airbnb/lottie-web).\n\nWhen a page contains multiple animations with different players specified, the _greater_ player will be loaded. So to load the light player, all animation musts set the `player=\"light\"` (or no player at all, as the default one is the `\"light\"`).\n\nThe lottie player is locally saved in the public folder (it's handled under the hood by astro/vite) so no external request is sent.\n\n### Animation loading\nThe lottie animations are not bundled in your page. They're asynchronously fetched when the page loading ends, when a small loader script is run. \n\nThe loader will\n- check if the page has any lottie animations\n- fetch the lottie player\n- download the animations (if one is used multiple times, it's downloaded once)\n- setup each the animation on the page\n- if the autoplay is `true`, the animation is started right away, otherwise the animation will play only when it's visible and paused when it exits the screen. This is achieved thanks to `IntersectionObserver`, with a visibility filter 0.01.\n- raise a document event `astro-lottie-loaded` when all animations are loaded and ready\n\n### Accessing the Lottie Player\nThis plugin registers a `astroLottie` global object for the page.\n\n```ts\nconst astroLottie = window.astroLottie;\nif (!astroLottie) {\n  // lottie is not registered! Either ...\n  // - no lottie animation is present on this page\n  // - lottie library failed to load  \n} else {\n  const animation = astroLottie.getAnimation(\"my-animation\");\n  animation.player.play();\n}\n```\n\nThe `AstroLottie` has two features:\n- getting a specific animation by a key\n- getting all animations present in the page\n\nThe full specification is:\n```ts\nexport type AstroLottie = {\n    /**\n     * Get a LottieAnimation by the configured id\n     */\n    getAnimation(id: string): LottieAnimation | undefined\n\n    /**\n     * Get a LottieAnimation from the hosting element container\n     */\n    getAnimation(from: { container: HTMLElement }): LottieAnimation | undefined\n\n    /**\n     * Get a LottieAnimation from the hosting element container\n     */\n    getAnimation(from: { elementId: string }): LottieAnimation | undefined\n\n    /**\n     * Get all the LottieAnimation for the current page\n     */\n    getAllAnimations(): LottieAnimation[]\n}\n```\n\nA `LottieAnimation` represents a single animation registered for the current page and is defined with:\n```ts\nexport type LottieAnimation = Readonly\u003c{\n    id: string                        // the specified id es: \u003cLottie id=\"my-animation\" /\u003e\n    config: LottieAnimationConfig     // the full lottie configuration of the Lottie element\n    container: HTMLElement            // the hosting dom element container\n    isLoaded: boolean                 // specify if the animation is successfully loaded\n    player?: AnimationItem            // this is the real Lottie player. It's defined when isLoaded is true\n}\u003e\n```\n\nThe `player` property is the Lottie player, typed by the Lottie library itself. You can checkout [Lottie](https://github.com/airbnb/lottie-web#usage) repository for the documentation.\n\n\nFor example if you need to start an animation on demand when a button is clicked.\n```ts\ndocument.querySelector(\"#play-button\").addEventListener(\"click\", () =\u003e {\n  const animation = astroLottie.getAnimation(\"my-animation\");\n  if (animation \u0026\u0026 animation.isLoaded) {\n    animation.player.play();\n  }\n});\n```\n\n### Animation ready event\nThe loader emit a document event `astro-lottie-loaded` when all animations are loaded and ready. The `details` property of the event, is the `astroLottie` global object.\n\n```ts\ndocument.addEventListener(\"astro-lottie-loaded\", e =\u003e {\n  const astroLottie = e.details;\n  const animations = astroLottie.getAllAnimations();\n});\n```\n\n## Reference\n### LottieAnimationConfig --\u003e the Lottie component Props\n| property | type                  | usage    | description                              | \n|:---------|:----------------------|:---------|:-----------------------------------------|\n| id       | `string`              | optional | used to access the relative lottie player via javascript |\n| src      | `string`              | required | the public path from where the animation will be downloaded |\n| player   | `\"light\"` \\| `\"full\"`  | optional(`\"light\"`)    | which lottie player to load |\n| loop     | `boolean`             | optional(`true`)      | play the animation on loop |\n| autoplay | `true` \\| `\"visible\"` | optional(`\"visible\"`) | starts the animation as soon it loads or only when it's visible on the page |\n| visibleThreshold | `number` | optional(`0`) | Range[0-1] for the visibility to start the animation: 1 means 100% visible, 0 means that just 1px will make the animation play. When multiple animations on the same page use different thresholds, the minimum will be used for all |\n\n\n\n## Types\nThis package is built in typescript so it has full typings support.\n\n## License\n[MIT](LICENSE) © [Giuseppe La Torre](https://github.com/giuseppelt)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiuseppelt%2Fastro-lottie","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgiuseppelt%2Fastro-lottie","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiuseppelt%2Fastro-lottie/lists"}