How Do You Install and Use heroicons-animated Icons in a React Project?

Updated

heroicons-animated is an open-source (MIT licensed) collection of 316 animated Heroicons built with Motion and Heroicons, distributed as copy-paste-ready React components. You add icons one at a time through the shadcn CLI rather than installing the whole set as a package, so your project only pulls in the icons you actually use. This works for any React project that already has Motion available; if you skip that dependency, the icons render but the animation won't run.

What you get

The library is a set of animated SVG icons for React, crafted with Motion and Heroicons. Per the project's own description, it is free, open-source under the MIT License, and "copy-paste ready." The creator notes the work was heavily inspired by lucide-animated by dmytro and by the animations.dev course.

Two things follow from that:

  • MIT license means you can use, modify, and ship the icons in commercial and personal projects without a separate license step.
  • Copy-paste ready means the icons arrive as source components in your repo, not as an opaque dependency you import from node_modules.

Prerequisites

Before adding icons, confirm:

  1. A React project. The components are React components, so you need a working React setup.
  2. Motion installed. The animations are built with Motion. If Motion isn't present, the icon component may still render as a static SVG but the animation behavior won't work.
  3. The shadcn CLI available. The documented install path uses shadcn@latest, so your project should be set up to run it (a components.json config or the ability to initialize one).

Adding a single icon

The project's documented flow adds icons individually by name. The example given on the site is academic-cap:

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

The same pattern works with other package runners:

npx shadcn@latest add @heroicons-animated/academic-cap
npm dlx shadcn@latest add @heroicons-animated/academic-cap
yarn dlx shadcn@latest add @heroicons-animated/academic-cap
bun dlx shadcn@latest add @heroicons-animated/academic-cap

Input: the icon name appended to the @heroicons-animated/ registry path. Action: the shadcn CLI fetches that icon's component source and writes it into your project's component directory. Expected result: a new component file for that icon appears in your components folder, ready to import.

To add a different icon, swap the name — for example @heroicons-animated/academic-cap becomes @heroicons-animated/<other-icon-name>. Since the collection has 316 icons, you add them one by one as your UI needs them.

Using the icon in your code

Once the CLI writes the component, import it from wherever your components live and render it like any other React component:

import AcademicCap from "@/components/icons/academic-cap";

export default function Example() {
  return <AcademicCap />;
}

The exact import path depends on where your shadcn setup places components — check the file the CLI created and match that path. Because the icon is now local source, you can open it and see exactly how the animation is wired.

Adjusting size, color, and animation

Because these are React components wrapping SVG, the usual SVG and React props apply:

  • Size — set width/height via props or a className with sizing utilities (for example a Tailwind h-6 w-6).
  • Color — control with className text/color utilities or currentColor, matching how you style other SVGs.
  • Animation behavior — since the animation is built with Motion, the component's own props or its internal Motion configuration govern how and when it animates. Open the generated file to see which props it exposes and adjust there.

If you need a specific trigger (hover, mount, in-view), check the component source first — the animation logic lives in that file, not behind a package API.

Common problems

Icon renders but doesn't animate. The most likely cause is a missing or mismatched Motion dependency. Confirm Motion is installed and that the version is compatible with what the component expects.

Import fails / module not found. The import path must match where the CLI actually wrote the file. Open your components directory, find the new file, and copy its real path rather than assuming a default location.

CLI doesn't recognize the registry. Make sure you're running shadcn@latest and that your project has the shadcn configuration the CLI needs. If the command errors on the @heroicons-animated/ registry, verify the registry path is spelled exactly as documented.

Animation looks wrong after customization. If you edited the component and the motion broke, compare against the original generated file — the Motion setup is easy to disturb when trimming props.

When to use this vs. a static icon set

Choose heroicons-animated when you specifically want motion in your icons and you're comfortable adding them as local source components. Because each icon is added individually, you keep control over what ships and can read the animation code directly.

If you only need static icons, a plain Heroicons or Lucide set is simpler — no Motion dependency, no per-icon CLI step. The trade-off is purely whether the animation earns its extra dependency and setup.