ドキュメント

ドキュメント

useAnimations は、React 向けの 300 個のアニメーションアイコンをまとめた、無料で MIT ライセンスのライブラリです。どのアイコンにもインタラクションが組み込まれていて、ループする、クリックで再生する、ホバーで再生する、のいずれかの動きをします。react-useanimations パッケージで使うことも、shadcn CLI で追加することもできます。

クイックスタート

npm install react-useanimations

import UseAnimations from 'react-useanimations';
import github from 'react-useanimations/lib/github';

export default function Header() {
  return <UseAnimations animation={github} size={32} />;
}

アイコンはテキストの色に追従し、それぞれ決まったインタラクションで再生されます。github はホバーしている間ループします。パッケージに依存関係はなく、内蔵のプレーヤー（gzip 圧縮後 8 kB）がアイコンを SVG として描画します。アイコンはそれぞれ独立したモジュールなので、バンドルに含まれるのはインポートしたアイコンだけです。

インタラクション

どのアイコンにも、デザイン時に想定したインタラクションが付いています。interaction prop で上書きできます。

ユーザーがモーション軽減を設定している場合、アイコンは動きません。ループは最初のフレームを表示し、ホバーやリプレイのアニメーションは再生されず、トグルはすぐに新しい状態に切り替わります。

Props

<UseAnimations animation={github} size={56} strokeColor="#4b5cff" style={{ padding: 8 }} />

それ以外の prop（className、aria-label、onClick など）はラッパーの <span> に渡されます。イベントハンドラーはアニメーションの処理より先に実行され、event.preventDefault() を呼ぶとアニメーションをスキップできます。

アイコンのインポート

アイコンは 1 つずつ react-useanimations/lib/<name> からインポートするか、react-useanimations/icons から複数まとめてインポートします：

import { github, heart, menu } from 'react-useanimations/icons';

どちらの方法でも、本番ビルドには使ったアイコンだけが含まれます。ただし開発サーバーやテストランナーはツリーシェイキングを行わないため、react-useanimations/icons を使うと全アイコンが読み込まれます。それが気になる場合は lib/<name> を使ってください。delete と package は予約語なので、deleteIcon と packageIcon としてインポートします。

制御型のトグル

import { useState } from 'react';
import UseAnimations from 'react-useanimations';
import menu from 'react-useanimations/lib/menu';

export function MenuButton() {
  const [open, setOpen] = useState(false);
  return (
    <UseAnimations
      animation={menu}
      size={40}
      active={open} // `open` がほかの場所で変わったときもアニメーションする
      onClick={() => setOpen(!open)}
    />
  );
}

アイコンを本物のボタンで包む

クリックできるアイコンは、render prop を使ってフォーカス可能な要素で包みましょう。eventProps は自分の要素に、animationProps はその中の <span> に渡します。こうすると、ボタンがキーボードフォーカスを受けたときにもホバーアニメーションが再生されます。

import heart from 'react-useanimations/lib/heart';

<UseAnimations
  animation={heart}
  size={32}
  render={(eventProps, animationProps) => (
    <button type="button" aria-label="Add to favorites" {...eventProps}>
      <span {...animationProps} />
    </button>
  )}
/>;

サイズと色

アイコンは 24 px または 32 px のアートボードに描かれたラインアイコンで、どのサイズでもくっきり表示されます。size にはピクセル数か任意の CSS の長さを指定します。

線は currentColor に追従するので、アイコンはテキストの色、ホバー時の色、ダークモードに自動で合わせます。色は strokeColor と fillColor、CSS の color、またはパスへのスタイル指定で変更できます。組み込みのルールは詳細度がゼロなので、自分で書いた CSS が必ず優先されます。

一部のアイコンは、自身の形に切り欠きを入れています（visibility、microphone、video、volume、notification の斜線、download のチェック、notification3 のバッジを囲むリング）。この切り欠きはページの背景色になり、明るいページでは白、color-scheme: dark のページでは暗い色になります。それ以外の背景では、--ua-knockout CSS 変数で指定してください（例：body { --ua-knockout: #0f172a; }）。

// Tailwind：色と線の太さ
<UseAnimations animation={github} className="text-indigo-500 [&_path]:stroke-[3]" />

Next.js とサーバーサイドレンダリング

コンポーネントには 'use client' が付いていて、アニメーションはブラウザーでのみ描画されます。そのため、サーバーコンポーネントや SSR フレームワーク（Next.js、Remix、Astro）から、dynamic(…, { ssr: false }) なしでレンダリングできます。アイコンのモジュールはただのデータなので、サーバーコンポーネントでインポートして props として渡せます。

shadcn/ui

どのアイコンも shadcn レジストリに登録されています。CLI がすぐに使えるコンポーネントを追加し、react-useanimations をインストールします：

npx shadcn@latest add https://useanimations.com/r/checkmark.json

import { AnimatedCheckmark } from '@/components/animations/checkmark';

<AnimatedCheckmark size={24} />;

コンポーネント名は Animated + PascalCase にしたアイコン ID（check-box → AnimatedCheckBox）で、components/animations/<id>.tsx に追加され、UseAnimations と同じ props を受け取ります。レジストリのインデックスは /r/registry.json です。npx shadcn@latest add @useanimations/checkmark のように短く書くには、components.json にレジストリを追加します：

{
  "registries": {
    "@useanimations": "https://useanimations.com/r/{name}.json"
  }
}

独自のアニメーション

import animationData from './my-animation.json';

<UseAnimations animation={{ animationData, interaction: 'hover' }} />;

独自のアニメーションは、アイコンと同じ Lottie JSON 形式である必要があります。プレーヤーが対応しているのはアイコンに必要な機能です。シェイプレイヤー、プリコンポジション、ヌルレイヤーと親子関係、パス、長方形、楕円、線、塗り、パスのトリミング、マスク、イージング付きのキーフレーム、停止キーフレーム、モーションパス、そして loopOut() と wiggle() のエクスプレッションです。グラデーション、テキストレイヤーや画像レイヤー、エフェクト、マットなどそれ以外のものは描画されず、未対応のレイヤー、シェイプ、エクスプレッションについてはコンソールに警告が出ます。

ファイルと icons.json

どのアイコンも、各アイコンのページから、または CORS を有効にした固定の URL からダウンロードできます：

icons.json には、すべてのアイコンの ID、タイトル、カテゴリ、検索キーワード、インタラクション、ファイル URL、サイズ、再生時間、react-useanimations のインポート文、shadcn のコマンドが載っています。npm パッケージにも同じデータが入っています。react-useanimations/catalog.json（メタデータ）、react-useanimations/icons（アニメーション）、react-useanimations/svg.json（静的 SVG）です。

React なしで使う

アイコンは標準的な Lottie JSON なので、どの Lottie プレーヤーでも https://useanimations.com/icons/<id>.json から、またはプロジェクトにコピーしたファイルから再生できます。React 以外では、インタラクションは自分で組む必要があります。ほかのプレーヤーや例は Lottie アイコンにまとめています。

一部のアイコンは After Effects のエクスプレッション（loopOut()、wiggle()）を使っていて、icons.json では requiresFullPlayer で示されています。Web では lottie_light ではなく lottie-web のフルビルドが必要で、ネイティブのプレーヤーはエクスプレッションを評価しません。

HTML と JavaScript

<div id="icon" style="width: 48px; height: 48px"></div>

<script src="https://cdn.jsdelivr.net/npm/lottie-web@5.13.0/build/player/lottie.min.js"></script>
<script>
  const el = document.getElementById('icon');
  const animation = lottie.loadAnimation({
    container: el,
    renderer: 'svg',
    loop: false,
    autoplay: false,
    path: 'https://useanimations.com/icons/archive.json',
  });
  // ホバー：乗ると順方向、離れると逆方向
  el.addEventListener('mouseenter', () => {
    animation.setDirection(1);
    animation.play();
  });
  el.addEventListener('mouseleave', () => {
    animation.setDirection(-1);
    animation.play();
  });
</script>

SVG レンダラーを使えば、React コンポーネントと同じようにアイコンをテキストの色に追従させられます：

#icon path[stroke^='rgb']:not([stroke='rgb(255,255,255)']) {
  stroke: currentColor;
}
#icon path[fill='rgb(0,0,0)'] {
  fill: currentColor;
}

Vue

<script setup>
import lottie from 'lottie-web';
import { onBeforeUnmount, onMounted, ref } from 'vue';

const el = ref(null);
let animation;
onMounted(() => {
  animation = lottie.loadAnimation({
    container: el.value,
    renderer: 'svg',
    loop: true,
    autoplay: true,
    path: 'https://useanimations.com/icons/loading.json',
  });
});
onBeforeUnmount(() => animation?.destroy());
</script>

<template>
  <div ref="el" style="width: 48px; height: 48px" />
</template>

React Native

import LottieView from 'lottie-react-native';

<LottieView source={require('./loading.json')} autoPlay loop style={{ width: 48, height: 48 }} />;

iOS

lottie-ios を使い、JSON をアプリのバンドルに入れた場合：

import Lottie
import SwiftUI

LottieView(animation: .named("loading"))
  .looping()
  .frame(width: 48, height: 48)

Android

Jetpack Compose で lottie-android を使い、JSON を res/raw に置いた場合：

val composition by rememberLottieComposition(LottieCompositionSpec.RawRes(R.raw.loading))
LottieAnimation(composition, iterations = LottieConstants.IterateForever, modifier = Modifier.size(48.dp))

Flutter

lottie パッケージを使う場合：

Lottie.asset('assets/loading.json', width: 48, height: 48)

パフォーマンスとアクセシビリティ

• 軽量： プレーヤーは gzip 圧縮後 8 kB で依存関係はなく、アイコン 1 個は 1〜15 kB（中央値 2 kB）です。
• 遅延描画： アニメーションはページのレンダリング後、ブラウザーでのみ描画されます。自動再生のループは画面外にスクロールされている間は一時停止し、アンマウント時にはすべてクリーンアップされます。
• デフォルトは装飾扱い： aria-label を渡さない限り、アイコンはスクリーンリーダーから隠されます（aria-hidden）。aria-label を渡すと画像として読み上げられます。アイコンだけのコントロールには、aria-label を付けた本物の <button> を使い（前述を参照）、トグルの状態は aria-pressed や aria-expanded で伝えてください。
• モーション軽減とタッチ操作： アイコンは prefers-reduced-motion を尊重し、タッチスクリーンでのタップではホバーアニメーションは始まりません。

AI コーディングエージェント

エージェントは icons.json またはパッケージ内の react-useanimations/catalog.json から、キーワードやインタラクションでアイコンを選び、そこに載っているインポート文や shadcn のコマンドを使えます。各アイコンのインポートの型定義にも、タイトル、キーワード、インタラクション、プレビューが含まれています。このドキュメントは Markdown 版を /documentation.md で公開していて、/llms.txt がサイト全体の索引になっています。

v2 からのアップグレード

ほとんどのアプリでは、v3 をインストールするだけでアップグレードは完了します。コンポーネント、react-useanimations/lib/<name> のインポート、v2 の 79 個のアイコンはすべてそのままです。以下の手順のうち、自分のコードに当てはまるものを進めてください。

1. v3 をインストールする

v3 は React 18 以降が必要で、依存関係はありません。アプリのほかの部分で使っていなければ、lottie-web も削除してください。

npm install react-useanimations@3
npm uninstall lottie-web

2. reverse を active に置き換える

active は完全な制御型です。active が変わるとアイコンがアニメーションし、クリックだけでは切り替わらないので、onClick で更新してください。reverse は v2 と同じように動きます（開始時の状態を決め、クリックでアイコンが切り替わる）が、非推奨です。どちらも click-toggle のアイコンにだけ効きます。4 つの円形矢印アイコンは、クリックで再生する動きに変わりました（手順 6 を参照）。

- <UseAnimations animation={checkBox} reverse={checked} onClick={toggle} />
+ <UseAnimations animation={checkBox} active={checked} onClick={toggle} />

3. 色を確認する

v2 のアイコンは、strokeColor を指定しない限り黒でした。v3 のアイコンはテキストの色（currentColor）に追従し、fillColor のデフォルトは strokeColor です。色付きのテキストやリンクの中にあるアイコンはその色に変わります。黒のままにしたい場合は、自分で色を指定してください：

<UseAnimations animation={github} strokeColor="#000" />

4. wrapperStyle、pathCss、options を移行する

• wrapperStyle は非推奨です。style を使ってください。
• pathCss は削除されました。クラスを使ってパスにスタイルを当ててください。
• options（lottie-web の設定）は lottie-web とともに削除されました。loop、autoplay、speed の props を使ってください。それ以外の lottie-web のオプションに相当するものはありません。

それでも pathCss や options を渡すと、警告が 1 回だけ出力され、値は無視されます。

- <UseAnimations animation={github} wrapperStyle={{ margin: 8 }} pathCss="stroke-width: 3px;" options={{ loop: true }} />
+ <UseAnimations animation={github} style={{ margin: 8 }} className="thick" loop />

.thick path {
  stroke-width: 3px;
}

5. ラッパー要素を確認する

ラッパーは <div> から inline-block の <span> に変わりました。これにより、ボタンやリンクの中に置いても有効な HTML になり、テキストの行内に収まります。ラッパーを div として指定している CSS を更新し、render prop では animationProps を <span> に展開してください：

  render={(eventProps, animationProps) => (
    <button type="button" aria-label="Like" {...eventProps}>
-     <div {...animationProps} />
+     <span {...animationProps} />
    </button>
  )}

また、aria-label を渡さない限り、アイコンはスクリーンリーダーから隠される（aria-hidden）ようになりました。単体で意味を持つアイコンには aria-label を付けてください。

6. インタラクションが変わったアイコンを確認する

インタラクションは useanimations.com の表示と一致するようになりました。v2 と同じ動きにしたいアイコンには、以前のインタラクションを渡してください：

* v2 ではポインターが乗ると 1 回再生し、離れると最初に戻っていました。いちばん近いのは hover-replay です。

<UseAnimations animation={zoomIn} interaction="loop" />

7. インポートを更新する

アイコンのインポートは react-useanimations/lib/<name> か react-useanimations/icons からに限られます。react-useanimations/lib/github/index や react-useanimations/lib/github/github.json のような v2 の内部ファイルパスは解決できなくなりました。Lottie JSON はアイコンの animationData で取得できます：

- import githubJson from 'react-useanimations/lib/github/github.json';
+ import github from 'react-useanimations/lib/github';
+ const githubJson = github.animationData;

react-useanimations/utils のパスは削除されました。型はパッケージからインポートしてください：

- import type { Animation, AnimationKey } from 'react-useanimations/utils';
+ import type { Animation, AnimationKey, Interaction, UseAnimationsProps } from 'react-useanimations';

Animation は { animationData, interaction } になりました。v2 の animationKey フィールドはなくなったので、自分で組み立てたオブジェクトでは代わりに interaction を使ってください。

そのほかの新機能

221 個のアイコンの追加（合計 300 個）、react-useanimations/icons からの複数アイコンの一括インポート、モーション軽減への対応、キーボードフォーカスでのホバー再生、タッチスクリーンでホバーアニメーションが止まったままにならない動作、回避策なしのサーバーサイドレンダリング、そして shadcn レジストリ。

ライセンス

アイコンとコードは MIT ライセンスで公開しています。個人・商用を問わず、使用、改変、再配布ができます。クレジット表記は必須ではありませんが、入れていただけるとうれしいです：

Animated icons by <a href="https://useanimations.com">useAnimations</a>

詳しい条件はライセンスと利用規約を参照してください。

よくある質問