Getting Started

Astro Icon is a straightforward icon system for the Astro framework. This guide assumes that you have an existing Astro project.

See the Astro installation guide if you are starting a brand new project.

Installation

Quick Install

The astro add command-line tool automates the installation for you. Run one of the following commands in a new terminal window. (If you aren’t sure which package manager you’re using, run the first command.) Then, follow the prompts, and type “y” in the terminal (meaning “yes”) for each one.

npx astro add astro-icon

pnpm astro add astro-icon

yarn astro add astro-icon

If you run into any issues, feel free to report them to us on GitHub and try the manual installation steps below.

Manual Install

First, install the astro-icon package using your package manager. Run one of the following commands in the terminal:

npm install astro-icon

pnpm add astro-icon

yarn add astro-icon

Then, apply this integration to your astro.config.* file using the integrations property:

import { defineConfig } from "astro/config";
 import icon from "astro-icon";

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

Add Icons

Add new icons to your site by creating .svg files in /src/icons/. Use sub-folders to organize your files and create multiple sets of icons.

Icons in the /src/icons/ directory can be automatically referenced by their slug, for example:

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

<!-- Embed the contents of the `/src/icons/logo.svg` file -->
<Icon name="logo" />

<!-- Embed the contents of the `/src/icons/logos/astro.svg` file -->
<Icon name="logos/astro" />

Next steps

Configure: Learn about additional icon options in “Customizing Icons”.
Components: Understand the built-in Icon component in the “Components” guide.
Deploy: Before you publish your project, refer to the “Deployment” guide.

Updating Astro Icon

Astro Icon is a third-party Astro integration, which are not yet supported by @astrojs/upgrade. Instead, you can upgrade astro-icon by running the following command in your terminal:

npm install astro-icon@latest

pnpm add astro-icon@latest

yarn add astro-icon@latest

See the Astro Icon changelog for a full list of the changes made in each release.

Troubleshooting Astro Icon

Use the Customizing Icons guide and project configuration reference pages to ensure that Astro Icon is configured and functioning properly. See the guides in the sidebar for help with additional topics.

If your answer cannot be found in these docs, please visit the full Astro Docs for complete Astro documentation. Your question may be answered by understanding how Astro works in general.

You can also check for any known Astro Icon issues on GitHub. Although this is not an official Astro package, we encourage you to join the Astro Discord and chat with the active, friendly Astro community!