What Is heroicons-animated and How Do You Add Animated Heroicons to a React Project?

heroicons-animated is an open-source (MIT licensed) collection of 316 animated icons for React, built with Motion and Heroicons. You add an icon by running the shadcn CLI command pnpm dlx shadcn@latest add @heroicons-animated/<icon-name>, which copies a ready-to-use animated SVG component into your project. This fits React projects that already use shadcn or are willing to adopt its CLI, and that want smooth icon animations without hand-authoring motion code.

What heroicons-animated actually is

The library is described as "an open-source (MIT License) collection of smooth animated 316 icons for your projects," crafted with Motion & Heroicons. Two things follow from that description:

• The icon shapes come from Heroicons. Heroicons is the static SVG set; heroicons-animated wraps those shapes in animation.
• The motion comes from Motion. Motion is the animation library powering the transitions, so the icons are React components rather than plain static SVGs.

The project is backed by the Vercel OSS Program, and its creator (aniket) notes the icons were "heavily inspired from the work of lucide-animated by dmytro" and by the animations.dev course. That lineage matters if you are comparing it to other animated sets — see the comparison section below.

How it differs from static Heroicons and other animated sets

The practical difference: with static Heroicons you get a shape and write your own animation; with heroicons-animated the animation is already part of the component you install. The creator explicitly credits lucide-animated as inspiration, so if you already use that library, heroicons-animated is a Heroicons-shaped alternative rather than a replacement for a different icon family.

Adding an icon to a React project

The documented path is the shadcn CLI. The page shows the package-manager options pnpm, npm, yarn, and bun, and the install pattern:

pnpm dlx shadcn@latest add @heroicons-animated/<icon-name>

The example icon name given on the page is academic-cap, so a concrete command would be:

pnpm dlx shadcn@latest add @heroicons-animated/academic-cap

Input: the icon name you want, taken from the library's icon list. Action: the CLI fetches that icon's component and adds it to your project (the same mechanism shadcn uses for other registry items). Expected result: an animated icon component you can import and render in your React app.

To pick an icon, browse the collection and use its name in place of <icon-name>. The page also lists the general install form pnpm dlx shadcn@latest @heroicons-animated/, which is the registry reference rather than a single-icon add.

Common sticking points

• You need a shadcn-compatible setup. The command is the shadcn CLI, so it assumes the CLI can write into your project. If your project isn't set up for shadcn, expect to configure that first.
• Icon names must match the library. academic-cap is the documented example; a name that isn't in the 316-icon set won't resolve.
• It's a copy-in, not a runtime dependency. Because the CLI adds the component to your codebase, you customize the file it produces rather than importing from a package at runtime.

Customizing the SVG and animations

The library is described as "fully customizable SVG icons with smooth animations," and because the CLI copies the component into your project, customization happens in your own file. In practice you adjust two layers:

• The SVG layer — the Heroicons shape: size, stroke, color, and any props you pass through.
• The motion layer — the Motion-driven animation: timing, easing, and what triggers it (for example, hover or mount).

Because both layers live in the installed component, you can change the animation without touching the icon geometry, or restyle the icon without breaking its motion.

Licensing and usage

The library is MIT licensed and described as free and open-source, with the creator inviting you to "use them, share your feedback." MIT is a permissive license, so the terms support use in personal and commercial projects; if you need to confirm exact obligations (for example, attribution requirements), check the license text in the repository rather than relying on the summary here. The page does not state any pricing, so treat it as an open-source project rather than assuming paid tiers or login requirements either way.

If your goal is animated Heroicons in React with minimal setup, the shadcn CLI add command is the whole workflow: pick a name, run the command, then edit the component it drops into your project.