DOCSEARCHbyAlgolia
Submit Docs

AnimateIcons Documentation

repository·main·Indexed 21 days ago

https://github.com/avijit07x/animateicons

A collection of 542 animated SVG icons for React applications built on motion/react. It provides the @animateicons/react package for direct imports, a CLI for adding individual icon source files to projects, and an MCP server (@animateicons/mcp) for AI coding agents. Features include hover and imperative animation triggers via refs, configurable sizing and coloring, and an interactive TUI for browsing icons.

Tokens
20.3K
Snippets
82
Records
94
Agent score
76%

What's inside AnimateIcons

  1. What is @animateicons/mcp?

    main
    The @animateicons/mcp package is a Model Context Protocol (MCP) server for AnimateIcons. It enables AI coding agents (such as Claude Code or Cursor) to interact with the AnimateIcons catalog. Specifically, it allows agents to search for icons and automatically insert animated React icon components directly into your project files.

  2. Requirements for using add_icon

    main

    When using the add_icon tool, ensure your project meets the following requirements:

    1. Utility Import: The generated icon components assume the existence of a cn utility imported from @/lib/utils (following the shadcn/ui convention).
    2. Runtime Dependency: The motion package must be installed in your project for the animations to function.

  3. Use the IconHandle type for generic animation helpers

    main

    Every icon in @animateicons/react exposes an imperative handle via a ref that implements the IconHandle type. This type provides two methods: startAnimation() and stopAnimation().

    Because all icons share this same IconHandle interface, you can write generic helper functions to control animations from parent elements (like buttons or cards) without needing icon-specific types.

    import type { IconHandle } from "@animateicons/react"

// The IconHandle type is the common interface for all icon refs
export function handleHover(
  e: React.MouseEvent,
  ref: React.RefObject<IconHandle | null>,
) {
  if (e.type === "mouseenter") ref.current?.startAnimation()
  if (e.type === "mouseleave") ref.current?.stopAnimation()
}

  4. Install @animateicons/react

    main

    Install the @animateicons/react package using your preferred package manager to access 542 animated SVG icons built on motion/react.

    npm i @animateicons/react

# or

pnpm add @animateicons/react

# or

yarn add @animateicons/react

# or

bun add @animateicons/react

  5. Add animated icons to your project

    main

    Use the add command to download and write icon components to your project. By default, icons are written to components/icons/.

    Usage:

    # Add a single icon
npx animateicons add bell-ring

# Add multiple icons
npx animateicons add bell-ring activity user

# Use prefixed registry IDs (e.g., lucide or huge)
npx animateicons add lu-bell-ring

    Important Notes:

    • Dependencies: Icons require motion. The CLI will print the appropriate installation command for your package manager.
    • Utility Functions: Icons follow the shadcn convention and attempt to import cn from @/lib/utils. If your project uses a components.json file, the CLI honors the aliases.utils setting. If you don't have a utility file, use the --with-utils flag to scaffold a minimal lib/utils.ts containing cn.
    • Ambiguity: If a bare name exists in multiple libraries, the CLI will prompt you to select the correct prefixed ID.
    npx animateicons add bell-ring

  6. Style AnimateIcons with props

    main

    AnimateIcons can be styled using standard props. Because icons use stroke="currentColor", they automatically inherit the text color from their parent or via CSS classes.

    Key styling props:

    • color: Sets the currentColor inline.
    • className: Applies CSS classes (e.g., Tailwind text-primary).
    • duration: A multiplier for animation speed (lower values result in faster animations).
    • isAnimated: A boolean to enable or disable hover animations.
    // Color - sets currentColor inline
<EyeIcon color="#f45b48" />

// Tailwind utility - works because icons stroke="currentColor"
<EyeIcon className="text-primary" />

// Speed - duration is a multiplier (lower = faster)
<EyeIcon duration={0.6} />

// Disable hover animation
<EyeIcon isAnimated={false} />

  8. Install the animateicons CLI

    main

    You can use the CLI via npx without installation, or install it globally to use the animateicons command directly in your terminal.

    Using npx (no installation required):

    npx animateicons add <icon-name>

    Global installation:

    npm i -g animateicons
animateicons add <icon-name>
    npm i -g animateicons

  9. Trigger icon animations on container hover

    main

    To create interactive UI elements like feature cards or status banners, you can trigger an AnimateIcon animation based on the hover state of its parent container.

    Instead of triggering the animation on the icon itself, use a useRef hook to capture the icon's handle (e.g., SparklesIconHandle) and call .startAnimation() and .stopAnimation() within the container's onMouseEnter and onMouseLeave event handlers. This makes the entire surface area of the container the trigger for the animation.

    import { useRef } from "react"
import { SparklesIcon, type SparklesIconHandle } from "@animateicons/react/lucide"

export function FeatureCard() {
	const ref = useRef<SparklesIconHandle>(null)

    return (
    	<div
    		onMouseEnter={() => ref.current?.startAnimation()}
    		onMouseLeave={() => ref.current?.stopAnimation()}
    		className="rounded-xl border p-5"
    	>
    		<SparklesIcon ref={ref} size={20} />
    		<p>Smart suggestions</p>
    	</div>
    )
}

  10. Add icons without dependencies using the CLI

    main

    If you prefer not to install the full @animateicons/react package as a dependency, you can use the animateicons CLI to add individual icon source files directly to your project. You can also use npx animateicons browse to interactively find icons.

    npx animateicons add bell-ring
npx animateicons browse

  11. Add AnimateIcons to your project using shadcn CLI

    main

    You can add individual AnimateIcons to your project using the shadcn CLI. This method copies the icon into your codebase as a single, editable .tsx file located at components/ui/<icon-name>.tsx.

    Prerequisites: Your project must already have shadcn installed. If not, follow the official shadcn installation guide.

    Steps:

    1. Browse the Lucide or Huge galleries.
    2. Copy the install command for the desired icon (or replace the icon identifier in the command below).
    3. Run the command in your terminal.
    4. Import the icon component from your local components/ui directory.
    pnpm dlx shadcn@latest add https://animateicons.in/r/lu-eye.json

  12. Connect the AnimateIcons MCP server to Claude Code

    main

    You can register the @animateicons/mcp server with Claude Code using a single command. This allows Claude Code to search the icon catalog and automatically write icon components into your project files.

    Note: After running the command, restart Claude Code (or reload your editor window) to ensure the new tools are registered.

    claude mcp add animateicons -- npx -y @animateicons/mcp