Documentation Astro

Astroを使ったWeb開発において、視覚的に洗練されたアイコンは欠かせません。 ここでは、Astroプロジェクトでアイコンを簡単に扱えるツール「astro-icon」を紹介し、Iconifyとの連携方法についても解説します。 Astroプロジェクトをスタイリッシュに演出するアイコンの導入がスムーズにできるようになります。

この記事で学べること

  • astro-iconのインストールと基本設定
  • Iconifyを使ったアイコンの検索と選択方法
  • アイコンのスタイリングとカスタマイズ
  • カスタムSVGアイコンの追加方法
  • パフォーマンスを考慮した最適化手法

astro-iconとIconifyとは

astro-icon

astro-iconは、Astroプロジェクトにアイコンを簡単に追加できる公式推奨のインテグレーションです。SVGアイコンをコンポーネントとして扱えるため、スタイリングや最適化が容易になります。

Iconify

Iconifyは、200,000以上のアイコンを提供する統合アイコンフレームワークです。Material Design Icons、Font Awesome、Bootstrap Iconsなど、100以上のアイコンセットを一つのAPIで利用できます。

特徴説明
豊富なアイコン200,000以上のアイコンを提供
統一されたAPI異なるアイコンセットを同じ方法で使用可能
SVGベース高品質でスケーラブル
軽量使用するアイコンのみがバンドルされる

astro-iconの導入

astro-iconはAstroプロジェクトに簡単にアイコンを追加できるツールです。以下の手順で導入を進めましょう。

プロジェクトのセットアップ

既存のAstroプロジェクトがある場合はこのステップをスキップしてください。新規プロジェクトの場合は以下のコマンドを実行してセットアップします。

npm create astro@latest

画面の指示に従ってプロジェクトを設定してください。

astro-iconのインストール

astro-iconをプロジェクトにインストールするには、プロジェクトのルートディレクトリで以下のコマンドを実行します。

# npmの場合
npm install astro-icon

# pnpmの場合
pnpm add astro-icon

# yarnの場合
yarn add astro-icon

Astro設定ファイルの更新

astro.config.mjsファイルを開き、astro-iconを統合します。

// astro.config.mjs
import { defineConfig } from 'astro/config';
import icon from 'astro-icon';

export default defineConfig({
  integrations: [icon()]
});

アイコンの基本的な使い方

Iconコンポーネントのインポート

アイコンを使用するためにAstroコンポーネント内でIconコンポーネントをインポートします。

---
import { Icon } from 'astro-icon/components';
---

<Icon name="mdi:account" />

mdi:accountは、Material Design Iconsセットからaccountアイコンを指定しています。

アイコン名の構成

アイコン名は セット名:アイコン名 の形式で指定します。

<!-- Material Design Icons -->
<Icon name="mdi:home" />

<!-- Font Awesome 6 Solid -->
<Icon name="fa6-solid:user" />

<!-- Bootstrap Icons -->
<Icon name="bi:github" />

<!-- Heroicons -->
<Icon name="heroicons:heart" />

サイズと色のカスタマイズ

HTML属性でサイズや色を簡単にカスタマイズできます。

---
import { Icon } from 'astro-icon/components';
---

<!-- サイズを指定 -->
<Icon name="mdi:account" width="32" height="32" />

<!-- 幅のみ指定（高さは自動調整） -->
<Icon name="mdi:account" width="48" />

<!-- CSSクラスを適用 -->
<Icon name="mdi:account" class="icon-primary" />

CSSでのスタイリング

---
import { Icon } from 'astro-icon/components';
---

<Icon name="mdi:heart" class="heart-icon" />

<style>
  .heart-icon {
    width: 24px;
    height: 24px;
    color: #ef4444; /* 赤色 */
    transition: transform 0.2s ease;
  }

  .heart-icon:hover {
    transform: scale(1.2);
  }
</style>

Iconifyを活用したアイコン選択

astro-iconの利点の一つは、Iconifyと連携していることです。Iconifyは100以上のアイコンセットを提供しており、Iconify公式ウェブサイトで多種多様なアイコンを検索できます。

Iconify - home of open source icons

Iconify - home of open source icons

Open source vector icons from all popular icon sets

icon-sets.iconify.design

検索バーでアイコンを探し、特定のアイコンセットやカテゴリーで絞り込みも可能です。 iconify検索

  1. 言語を選択します。
  2. 表示されるコードをコピーします。 iconifyコピー

見つけたアイコンは次のように貼り付け、使用できます。

<Icon name="mdi:user" />

このように、Font AwesomeやBootstrap Iconsなど多くのアイコンセットをAstroプロジェクトに簡単に追加できます。

人気のアイコンセット一覧

よく使われるアイコンセットとその特徴を紹介します。

アイコンセットプレフィックス特徴アイコン数
Material Design IconsmdiGoogleが提供する汎用的なアイコン7,000+
Font Awesome 6fa6-solid, fa6-regular定番のアイコンセット2,000+
HeroiconsheroiconsTailwind CSS チームが作成450+
Bootstrap IconsbiBootstrap公式アイコン1,800+
LucidelucideFeather Iconsの拡張版1,000+
Phosphor Iconsph柔軟なウェイト対応6,000+
Simple Iconssimple-iconsブランドロゴ専用2,500+

使用例：複数のアイコンセットを組み合わせる

---
import { Icon } from 'astro-icon/components';
---

<nav class="social-links">
  <!-- Simple Icons でブランドロゴ -->
  <a href="https://github.com">
    <Icon name="simple-icons:github" />
  </a>
  <a href="https://twitter.com">
    <Icon name="simple-icons:x" />
  </a>

  <!-- Heroicons でUI要素 -->
  <button>
    <Icon name="heroicons:magnifying-glass" />
    検索
  </button>
</nav>

特殊なアイコンセットの使用

一部の特殊なアイコンセット（例：logos）は、astro-iconとは別途パッケージをインストールする必要があります。 iconify　logos

アイコンセットのインストール

例えば、logosセットを使う場合、以下のコマンドでインストールします。

npm install @iconify-json/logos

よく使うアイコンセットのインストール例

# 複数のアイコンセットを一度にインストール
npm install @iconify-json/mdi @iconify-json/heroicons @iconify-json/simple-icons

# ブランドロゴ用
npm install @iconify-json/logos @iconify-json/simple-icons

# 開発ツールのアイコン
npm install @iconify-json/devicon

インストール後の使用方法

インストールしたアイコンセットを使用するには、次のようにコードを記述します。

---
import { Icon } from 'astro-icon/components';
---

<!-- プログラミング言語のロゴ -->
<Icon name="logos:javascript" />
<Icon name="logos:typescript-icon" />
<Icon name="logos:react" />
<Icon name="logos:vue" />

<!-- 開発ツールのアイコン -->
<Icon name="devicon:vscode" />
<Icon name="devicon:git" />

この方法を使えば、一般的なアイコンセットに加えて、プロジェクト固有のニーズに対応した特殊なアイコンセットも利用できます。

カスタムアイコンの使用

カスタムSVGアイコンをプロジェクトに追加することも可能です。

ディレクトリ構造

カスタムアイコンを使用するには、src/icons/ディレクトリにSVGファイルを配置します。

src/
├── icons/
│   ├── my-logo.svg
│   ├── custom-arrow.svg
│   └── brand/
│       ├── logo-light.svg
│       └── logo-dark.svg
└── pages/
    └── index.astro

カスタムアイコンの使用方法

---
import { Icon } from 'astro-icon/components';
---

<!-- src/icons/my-logo.svg を参照 -->
<Icon name="my-logo" />

<!-- src/icons/brand/logo-light.svg を参照 -->
<Icon name="brand/logo-light" />

SVGファイルの準備

カスタムSVGを作成する際のポイント：

<!-- 推奨：viewBoxを指定し、width/heightは指定しない -->
<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
  <path d="M12 2L2 7l10 5 10-5-10-5z" fill="currentColor"/>
</svg>
  • viewBoxを指定することでスケーラブルになる
  • fill="currentColor"を使うとCSSのcolorプロパティで色を変更可能
  • widthとheightは指定せず、使用時にサイズを決める

実践的なスタイリング例

ボタン内のアイコン

---
import { Icon } from 'astro-icon/components';
---

<button class="btn-primary">
  <Icon name="mdi:plus" class="btn-icon" />
  新規作成
</button>

<button class="btn-secondary">
  <Icon name="mdi:download" class="btn-icon" />
  ダウンロード
</button>

<style>
  button {
    display: inline-flex;
    align-items: center;
    gap: 0.5rem;
    padding: 0.75rem 1.5rem;
    border: none;
    border-radius: 0.5rem;
    font-size: 1rem;
    cursor: pointer;
    transition: background-color 0.2s;
  }

  .btn-primary {
    background-color: #3b82f6;
    color: white;
  }

  .btn-primary:hover {
    background-color: #2563eb;
  }

  .btn-secondary {
    background-color: #e5e7eb;
    color: #374151;
  }

  .btn-icon {
    width: 1.25rem;
    height: 1.25rem;
  }
</style>

アイコンリスト

---
import { Icon } from 'astro-icon/components';

const features = [
  { icon: 'mdi:rocket-launch', text: '高速なパフォーマンス' },
  { icon: 'mdi:shield-check', text: 'セキュリティ対策' },
  { icon: 'mdi:puzzle', text: '柔軟なカスタマイズ' },
];
---

<ul class="feature-list">
  {features.map(feature => (
    <li>
      <Icon name={feature.icon} class="feature-icon" />
      <span>{feature.text}</span>
    </li>
  ))}
</ul>

<style>
  .feature-list {
    list-style: none;
    padding: 0;
  }

  .feature-list li {
    display: flex;
    align-items: center;
    gap: 0.75rem;
    padding: 0.75rem 0;
  }

  .feature-icon {
    width: 1.5rem;
    height: 1.5rem;
    color: #10b981;
    flex-shrink: 0;
  }
</style>

アニメーション付きアイコン

---
import { Icon } from 'astro-icon/components';
---

<!-- ローディングスピナー -->
<Icon name="mdi:loading" class="spinner" />

<!-- ホバーで回転 -->
<Icon name="mdi:cog" class="settings-icon" />

<!-- パルスアニメーション -->
<Icon name="mdi:bell" class="notification-icon" />

<style>
  .spinner {
    width: 24px;
    height: 24px;
    animation: spin 1s linear infinite;
  }

  @keyframes spin {
    from { transform: rotate(0deg); }
    to { transform: rotate(360deg); }
  }

  .settings-icon {
    width: 24px;
    height: 24px;
    transition: transform 0.3s ease;
  }

  .settings-icon:hover {
    transform: rotate(90deg);
  }

  .notification-icon {
    width: 24px;
    height: 24px;
    animation: pulse 2s ease-in-out infinite;
  }

  @keyframes pulse {
    0%, 100% { opacity: 1; }
    50% { opacity: 0.5; }
  }
</style>

エラーの対応

下記のようにエラーが出た場合はこちらをご参照ください。

Error when evaluating SSR module [...]/astro.config.mjs: failed to import "astro-icon"
SyntaxError: The requested module 'cheerio' does not provide an export named 'default'
  at ModuleJob._instantiate (node:internal/modules/esm/module_job:124:21)
  at async ModuleJob.run (node:internal/modules/esm/module_job:190:5)
【Astro】astro-iconとcheerioの互換性問題 - トラブルシューティング

【Astro】astro-iconとcheerioの互換性問題 - トラブルシューティング

Astroプロジェクトでよく使用されるAstro-IconとCheerioの互換性問題に関する詳細なトラブルシューティングガイドです。エラーの原因と解決方法をわかりやすく説明しています。

nexunity.tech

よくあるエラーと解決方法

エラー原因解決方法
Unknown icon nameアイコンセットがインストールされていないnpm install @iconify-json/セット名
Cannot find moduleインポートパスが間違っているastro-icon/componentsからインポート
cheerio エラー依存関係の問題上記リンクを参照

パフォーマンス最適化のヒント

大規模なプロジェクトや大量のアイコンを使用する場合、パフォーマンスを最適化するために使用するアイコンセットを絞り込むことが重要です。

include オプションで使用アイコンを制限

astro.config.mjsファイルで、使用するアイコンセットを特定のアイコンに制限することができます。 以下の設定では、Material Design Iconsの全アイコンを含めつつ、Font Awesome 6 Solidとlogosセットから特定のアイコンのみを使用するように設定しています。

// astro.config.mjs
import { defineConfig } from 'astro/config';
import icon from 'astro-icon';

export default defineConfig({
  integrations: [icon({
    include: {
      // 全アイコンを含める
      mdi: ['*'],
      // 特定のアイコンのみ含める
      'fa6-solid': ['user', 'home', 'cog', 'search'],
      logos: ['javascript', 'typescript', 'react', 'vue'],
      heroicons: ['heart', 'star', 'check-circle'],
    },
  })],
});

パフォーマンス最適化のベストプラクティス

  1. 必要なアイコンのみを指定: ['*']の使用は最小限に
  2. アイコンセットを統一: 複数のセットを混在させず、1〜2種類に絞る
  3. カスタムアイコンの活用: 頻繁に使うアイコンはカスタムSVGとして配置
  4. 遅延読み込みの検討: ファーストビュー外のアイコンは遅延読み込み

ビルドサイズの確認

# ビルドして出力サイズを確認
npm run build

# 詳細な分析（viteのビルド分析を使用）
npx vite-bundle-visualizer

まとめ

astro-iconとIconifyを活用することで、Astroプロジェクトに簡単にアイコンを追加できます。

ポイントの振り返り

  • 導入: npm install astro-iconで簡単にセットアップ
  • 使い方: <Icon name="セット名:アイコン名" />の形式で指定
  • スタイリング: CSSで自由にカスタマイズ可能
  • カスタムアイコン: src/icons/にSVGを配置して使用
  • 最適化: includeオプションで必要なアイコンのみをバンドル

アイコンの使用は、デザイン面でのアクセントとして役立つだけでなく、UIをより直感的でユーザーフレンドリーにします。 さまざまなアイコンを使用してプロジェクトのレイアウトを強化し、アイコンのアニメーションやインタラクションを追加することを検討してみてください。

参考文献

円