auto-animate

AutoAnimate - エラー防止ガイド

パッケージ：@formkit/[email protected] (current) フレームワーク：React、Vue、Solid、Svelte、Preact 最終更新日：2026-01-21

---

SSR セーフなパターン（Cloudflare Workers／Next.js では重要）

// Use client-only import to prevent SSR errors
import { useState, useEffect } from "react";

export function useAutoAnimateSafe<T extends HTMLElement>() {
  const [parent, setParent] = useState<T | null>(null);

  useEffect(() => {
    if (typeof window !== "undefined" && parent) {
      import("@formkit/auto-animate").then(({ default: autoAnimate }) => {
        autoAnimate(parent);
      });
    }
  }, [parent]);

  return [parent, setParent] as const;
}

重要な理由：Issue #1（SSR／Next.js のインポートエラー）を防止します。AutoAnimate は、サーバーでは利用できない DOM API を使用します。

---

既知の問題の防止（記録されているエラー 15 件）

このスキルでは、記録されている問題 15 件を防止します。

Issue #1：SSR／Next.js のインポートエラー

エラー："Can't import the named export 'useEffect' from non EcmaScript module" ソース：https://github.com/formkit/auto-animate/issues/55 発生する理由：AutoAnimate は、サーバーでは利用できない DOM API を使用します。 防止策：動的インポートを使用します（templates/vite-ssr-safe.tsx を参照）。

Issue #2：親要素の条件付きレンダリング

エラー：親要素が条件付きの場合、アニメーションが動作しません。 ソース：https://github.com/formkit/auto-animate/issues/8 発生する理由：存在しない要素には ref を設定できません。 防止策：

React のパターン：

// ❌ Wrong
{showList && <ul ref={parent}>...</ul>}

// ✅ Correct
<ul ref={parent}>{showList && items.map(...)}</ul>

Vue.js のパターン：

<ul v-if="showList" ref="parent">
  <li v-for="item in items" :key="item.id">{{ item.text }}</li>
</ul>


<ul ref="parent">
  <li v-if="showList" v-for="item in items" :key="item.id">
    {{ item.text }}
  </li>
</ul>

ソース：React の Issue #8、Vue の Issue #193

Issue #3：一意のキーがない

エラー：項目が正しくアニメーションしない、またはちらつきます。 ソース：公式ドキュメント 発生する理由：React がどの項目に変更があったか追跡できません。 防止策：必ず一意で安定したキー（key={item.id}）を使用します。

Issue #4：Flexbox の幅と揺れの問題

エラー：要素が滑らかにアニメーションせず、指定幅に切り替わるか、削除時にコンテナーが揺れます。 ソース：公式ドキュメント、Issue #212 発生する理由：flex-grow: 1 は周囲のコンテンツを待つため、タイミングの問題が発生します。 防止策：アニメーションする要素には、flex-grow ではなく明示的な幅を指定します。

// ❌ Wrong - causes shaking
<ul ref={parent} style={{ display: 'flex' }}>
  {items.map(item => (
    <li key={item.id} style={{ flex: '1 1 auto' }}>{item.text}</li>
  ))}
</ul>

// ✅ Correct - fixed sizes
<ul ref={parent} style={{ display: 'flex', gap: '1rem' }}>
  {items.map(item => (
    <li
      key={item.id}
      style={{ minWidth: '200px', maxWidth: '200px' }}
    >
      {item.text}
    </li>
  ))}
</ul>

メンテナーからの注意：flex コンテナーには固定サイズが必要であることを、justin-schroeder が確認しています。

Issue #5：テーブル行の表示に関する問題

エラー：行の削除時にテーブル構造が崩れます。 ソース：https://github.com/formkit/auto-animate/issues/7 発生する理由：Display: table-row がアニメーションと競合します。 防止策：個々の行ではなく <tbody> に適用するか、div ベースのレイアウトを使用します。

Issue #6：Jest のテストエラー

エラー："Cannot find module '@formkit/auto-animate/react'" ソース：https://github.com/formkit/auto-animate/issues/29 発生する理由：Jest が ESM エクスポートを正しく解決できません。 防止策：jest.config.js で moduleNameMapper を設定します。

Issue #7：esbuild との互換性

エラー："Path '.' not exported by package" ソース：https://github.com/formkit/auto-animate/issues/36 発生する理由：ESM／CommonJS の条件が一致していません。 防止策：ESM モジュールを適切に処理するよう esbuild を設定します。

Issue #8：CSS の position による副作用

エラー：AutoAnimate の追加後にレイアウトが崩れます。 ソース：公式ドキュメント 発生する理由：親要素に自動的に position: relative が設定されます。 防止策：CSS で position の変更を考慮するか、明示的に設定します。

Issue #9：Vue／Nuxt の登録エラー

エラー："Failed to resolve directive: auto-animate" ソース：https://github.com/formkit/auto-animate/issues/43 発生する理由：プラグインが正しく登録されていません。 防止策：Vue／Nuxt の設定でプラグインを正しく設定します（references/ を参照）。

Nuxt 3 に関する注意：v0.8.2 以降（2024 年 4 月）が必要です。それ以前のバージョンには ESM インポートの問題があり、Daniel Roe によって修正されました。Issue #199 を参照してください。

Issue #10：Angular の ESM の問題

エラー："ESM-only package" でビルドに失敗します。 ソース：https://github.com/formkit/auto-animate/issues/72 発生する理由：CommonJS ビルド環境です。 防止策：Angular Package Format 用に ng-packagr を設定します。

Issue #11：React 19 StrictMode の二重呼び出しバグ

エラー：React 19 StrictMode で子要素のアニメーションが動作しません ソース：https://github.com/formkit/auto-animate/issues/232 発生理由：StrictMode が useEffect を 2 回呼び出し、autoAnimate の初期化が 2 回実行されます 予防策：ref を使って初期化を追跡します

// ❌ Wrong - breaks in StrictMode
const [parent] = useAutoAnimate();

// ✅ Correct - prevents double initialization
const [parent] = useAutoAnimate();
const initialized = useRef(false);

useEffect(() => {
  if (initialized.current) return;
  initialized.current = true;
}, []);

注：React 19 では、開発環境で StrictMode がデフォルトで有効になります。これは、すべての React 19 以降のプロジェクトに影響します。

Issue #12：ビューポート外でアニメーションが壊れる

エラー：リストがビューポート外にあると、アニメーションが壊れます ソース：https://github.com/formkit/auto-animate/issues/222 発生理由：Chrome は画面外の要素に対して Animation API を実行しない場合があります 予防策：autoAnimate を適用する前に、親要素が表示されていることを確認します

const isInViewport = (element) => {
  const rect = element.getBoundingClientRect();
  return rect.top >= 0 && rect.bottom <= window.innerHeight;
};

useEffect(() => {
  if (parent.current && isInViewport(parent.current)) {
    autoAnimate(parent.current);
  }
}, [parent]);

Issue #13：削除された要素が既存のコンテンツに重なる

エラー：フェードアウト中に、削除されたアイテムがほかのアイテムに重なります ソース：https://github.com/formkit/auto-animate/issues/231 発生理由：終了アニメーションで z-index が維持され、表示中のコンテンツに重なります 予防策：z-index を明示的に処理します

// CSS workaround
<style>{`
  [data-auto-animate-target] {
    z-index: -1 !important;
  }
`}</style>

Issue #14：ドラッグ＆ドロップ中に無効化できない

エラー：enable(false) を呼び出しても、ドラッグ中のアニメーションが防止されません ソース：https://github.com/formkit/auto-animate/issues/215 発生理由：ドラッグの途中では無効化が確実に機能しません 予防策：ドラッグ中は ref を条件付きで削除します

const [isDragging, setIsDragging] = useState(false);
const [parent] = useAutoAnimate();

return (
  <ul ref={isDragging ? null : parent}>
    {/* items */}
  </ul>
);

Issue #15：CSS Transform による親要素の位置バグ

エラー：親要素に transform を適用した後、アイテムが誤った位置からアニメーションします ソース：https://github.com/formkit/auto-animate/issues/227 発生理由：アイテムが transform 適用前の元の位置を記憶しています 予防策：transform が完了するまで autoAnimate の適用を遅らせます

useEffect(() => {
  if (showList && parent.current) {
    setTimeout(() => {
      autoAnimate(parent.current);
    }, 300); // Match CSS transition duration
  }
}, [showList]);

---

重要なルール（エラー防止）

必ず行うこと

✅ 一意で安定したキーを使用する - key={item.id} を使い、key={index} は使わない ✅ 親要素を DOM に残す - 親の ref 要素は常にレンダリングします ✅ SSR ではクライアント専用にする - サーバー環境では動的インポートを使用します ✅ アクセシビリティに配慮する - disrespectUserMotionPreference: false を維持します ✅ モーションを無効にしてテストする - アニメーションなしでも UI が動作することを確認します ✅ 幅を明示的に指定する - アニメーション対象の要素では flex-grow を避けます ✅ テーブルでは tbody に適用する - 個々の行には適用しません

絶対に行わないこと

❌ 親要素を条件付きにする - {show && <ul ref={parent}>} ❌ インデックスをキーとして使う - key={index} はアニメーションを壊します ❌ SSR を無視する - Cloudflare Workers/Next.js で動作しなくなります ❌ アニメーションを強制する - disrespectUserMotionPreference: true はアクセシビリティを損ないます ❌ テーブルを直接アニメーションさせる - tbody または div ベースのレイアウトを使用します ❌ 一意なキーを省略する - 適切なアニメーションに必須です ❌ 複雑なアニメーションを使う - 代わりに Motion を使用します

注：AutoAnimate は prefers-reduced-motion を自動的に尊重します（無効にしないでください）。

---

コミュニティのヒント（コミュニティ提供）

注：これらのヒントはコミュニティのディスカッションから得られたものです。お使いのバージョンで確認してください。

ヒント：パッケージのモックによるテストのフリーズを防ぐ

ソース：Issue #230 | 確度：MEDIUM 適用対象：v0.8.2+

パッケージをモックすると、テストが約 10 秒間フリーズする場合があります。ResizeObserver のモックを追加してください：

// jest.setup.js
global.ResizeObserver = jest.fn().mockImplementation(() => ({
  observe: jest.fn(),
  unobserve: jest.fn(),
  disconnect: jest.fn(),
}));

// __mocks__/@formkit/auto-animate.js
const autoAnimate = jest.fn(() => () => {});
const useAutoAnimate = jest.fn(() => [null, jest.fn(), jest.fn()]);
module.exports = { default: autoAnimate, useAutoAnimate };

ヒント：メモリリークの防止

ソース：Issue #180 | 確度：LOW 適用対象：全バージョン

長時間稼働する SPA では、適切にクリーンアップしてください：

useEffect(() => {
  const cleanup = autoAnimate(parent.current);
  return () => cleanup && cleanup();
}, []);

// useAutoAnimate hook handles cleanup automatically
const [parent] = useAutoAnimate(); // Preferred

---

パッケージのバージョン

最新：@formkit/[email protected] (Sept 5, 2025)

最近のリリース：

• v0.9.0 (Sept 5, 2025) - 現在の安定版
• v0.8.2 (April 10, 2024) - Nuxt 3 の ESM インポートと ResizeObserver ガードを修正

{
  "dependencies": {
    "@formkit/auto-animate": "^0.9.0"
  }
}

フレームワークの互換性：React 18+、Vue 3+、Solid、Svelte、Preact

重要：Nuxt 3 ユーザーには v0.8.2+ が必要です。それ以前のバージョンには ESM インポートの問題があります

---

公式ドキュメント

• 公式サイト: https://auto-animate.formkit.com
• GitHub: https://github.com/formkit/auto-animate
• npm: https://www.npmjs.com/package/@formkit/auto-animate
• React ドキュメント: https://auto-animate.formkit.com/react

---

テンプレートと参考資料

同梱リソースを参照してください：

• templates/ - コピーして使える例（SSR 対応、アコーディオン、トースト、フォーム）
• references/ - CSS の競合、SSR パターン、ライブラリの比較