---
title: "Auto-Import SVG Icons in Astro + React with Unplugin Icons"
description: "How to auto-import SVG icons on demand in an Astro app with React using Unplugin Icons, step by step."
source: "https://www.launchfa.st/blog/react-astro-unplugin-icons"
author: "Rishi Raj Jain"
created_at: 2024-06-05T00:00:00.000Z
updated_at: 2026-07-02T00:00:00.000Z
---
> **Site index for agents**
> Fetch https://www.launchfa.st/llms.txt to discover every page on this site.
> Every page is also available as Markdown by appending `.md` to its URL.
In this guide, you will learn how to use [Unplugin Icons](https://github.com/unplugin/unplugin-icons) in an Astro application using React. You will go through the process of setting up a new Astro project with React, configuring Unplugin Icons, and using them to leverage a huge collection of icons in your application.
## Prerequisites
You'll need the following:
- [Node.js 20](https://nodejs.org/en/blog/announcements/v20-release-announce) or later
## Table Of Contents
- [Create a new Astro application](#create-a-new-astro-application)
- [Integrate React in your Astro project](#integrate-react-in-your-astro-project)
- [Integrate Unplugin Icons in your Astro project](#integrate-unplugin-icons-in-your-astro-project)
- [Install the Unplugin Icons dependencies](#install-the-unplugin-icons-dependencies)
- [Create Type Definitions for Unplugin Icons](#create-type-definitions-for-unplugin-icons)
- [Use Unplugin Icons in the index route](#use-unplugin-icons-in-the-index-route)
- [Build and Test your Astro application locally](#build-and-test-your-astro-application-locally)
## Create a new Astro application
Let’s get started by creating a new Astro project. Execute the following command:
```bash
npm create astro@latest my-app
```
`npm create astro` is the recommended way to scaffold an Astro project quickly.
When prompted, choose:
- `Empty` when prompted on how to start the new project.
- `Yes` when prompted if you plan to write TypeScript.
- `Strict` when prompted how strict TypeScript should be.
- `Yes` when prompted to install dependencies.
- `Yes` when prompted to initialize a git repository.
Once that’s done, you can move into the project directory and start the app:
```bash
cd my-app
npm run dev
```
The app should be running on [localhost:4321](http://localhost:4321/).
Now, let's move on to integrate React in your Astro application.
## Integrate React in your Astro project
Execute the following command to integrate React in your Astro project:
```bash
npx astro add react
```
`npx` allows us to execute npm package binaries without having to first install them globally.
When prompted, choose the following:
- `Yes` when prompted whether to install the React dependencies.
- `Yes` when prompted whether to make changes to the Astro configuration file.
- `Yes` when prompted whether to make changes to `tsconfig.json` file.
Now, let's move on to integrating Unplugin Icons in your Astro application.
## Integrate Unplugin Icons in your Astro project
### Install the Unplugin Icons dependencies
Execute the commands below to install the necessary packages for using Unplugin Icons with React in Astro:
```bash
# unplugin-icons package for Vite compiler
npm i -D unplugin-icons
# @iconify/json package for the icons collection
npm i -D @iconify/json
# @svgr/core and @svgr/plugin-jsx packages for React compatibility
npm i -D @svgr/core @svgr/plugin-jsx
```
The command installs the following libraries:
- `unplugin-icons`: A package to access thousands of icons as components on-demand universally.
- `@iconify/json`: A big collection of open source vector icons, all validated, cleaned up and converted to the same easy to use format.
- `@svgr/core`: A package to transform SVGs into React components.
- `@svgr/plugin-jsx`: A package to transform SVG into JSX.
Further, perform the following additions in `astro.config.mjs` to use the Unplugin Icons integration:
```tsx
// File: astro.config.mjs
import react from "@astrojs/react";
import Icons from "unplugin-icons/vite"; // [!code ++] // [!code focus]
import { defineConfig } from "astro/config";
export default defineConfig({
integrations: [
react(),
vite: { // [!code ++] // [!code focus]
plugins: [ // [!code ++] // [!code focus]
Icons({ // [!code ++] // [!code focus]
jsx: "react", // [!code ++] // [!code focus]
compiler: "jsx", // [!code ++] // [!code focus]
autoInstall: true, // [!code ++] // [!code focus]
}), // [!code ++] // [!code focus]
Icons({ // [!code ++] // [!code focus]
compiler: "astro", // [!code ++] // [!code focus]
autoInstall: true, // [!code ++] // [!code focus]
}), // [!code ++] // [!code focus]
], // [!code ++] // [!code focus]
}, // [!code ++] // [!code focus]
],
});
```
As learnt from a [GitHub issue](https://github.com/unplugin/unplugin-icons/issues/253), it is wise to use both compiler modes, i.e. with React and Astro. This allows the usage of Unplugin Icons in both React and Astro components in your Astro application.
### Create Type Definitions for Unplugin Icons
To make sure that you can leverage the type definitions of the Unplugin Icons using React in Astro, you would want to globally define such specific Icon imports as React component imports.
To do so, update the `env.d.ts` in the `src` directory with the following code:
```tsx
///
declare module "virtual:icons/*" { // [!code ++] // [!code focus]
import type { SVGProps } from "react"; // [!code ++] // [!code focus]
import type React from "react"; // [!code ++] // [!code focus]
const component: (props: SVGProps) => React.ReactElement; // [!code ++] // [!code focus]
export default component; // [!code ++] // [!code focus]
} // [!code ++] // [!code focus]
```
The code above simply marks each import done via `virtual:icons` to be considered as React components in your Astro application.
### Use Unplugin Icons in the index route
Finally, import the icon and use it in your Astro (or React) component with the following code:
```astro
---
import MdiAlarmOff from "virtual:icons/mdi/alarm-off"; // [!code ++] // [!code focus]
---
Astro
Astro
// [!code ++] // [!code focus]
```
The code above imports an icon as a React component in the index route.
You're all done now!
## Build and Test your Astro application locally
To test the application, prepare a build and run the preview server using the command below:
```bash
npm run build && npm run preview
```
## Conclusion
In this guide, you learned how to use Unplugin Icons with React in an Astro application.
Using a different stack? Check out our guide on [Unplugin Icons in Next.js](/blog/nextjs-unplugin-icons).
If you have any questions or comments, feel free to reach out to me on [Twitter](https://twitter.com/direct_messages/create/rishi_raj_jain_).
In this guide, you will learn how to use [Unplugin Icons](https://github.com/unplugin/unplugin-icons) in an Astro application using React. You will go through the process of setting up a new Astro project with React, configuring Unplugin Icons, and using them to leverage a huge collection of icons in your application.
## Prerequisites
You'll need the following:
- [Node.js 20](https://nodejs.org/en/blog/announcements/v20-release-announce) or later
## Table Of Contents
- [Create a new Astro application](#create-a-new-astro-application)
- [Integrate React in your Astro project](#integrate-react-in-your-astro-project)
- [Integrate Unplugin Icons in your Astro project](#integrate-unplugin-icons-in-your-astro-project)
- [Install the Unplugin Icons dependencies](#install-the-unplugin-icons-dependencies)
- [Create Type Definitions for Unplugin Icons](#create-type-definitions-for-unplugin-icons)
- [Use Unplugin Icons in the index route](#use-unplugin-icons-in-the-index-route)
- [Build and Test your Astro application locally](#build-and-test-your-astro-application-locally)
## Create a new Astro application
Let’s get started by creating a new Astro project. Execute the following command:
```bash
npm create astro@latest my-app
```
`npm create astro` is the recommended way to scaffold an Astro project quickly.
When prompted, choose:
- `Empty` when prompted on how to start the new project.
- `Yes` when prompted if you plan to write TypeScript.
- `Strict` when prompted how strict TypeScript should be.
- `Yes` when prompted to install dependencies.
- `Yes` when prompted to initialize a git repository.
Once that’s done, you can move into the project directory and start the app:
```bash
cd my-app
npm run dev
```
The app should be running on [localhost:4321](http://localhost:4321/).
Now, let's move on to integrate React in your Astro application.
## Integrate React in your Astro project
Execute the following command to integrate React in your Astro project:
```bash
npx astro add react
```
`npx` allows us to execute npm package binaries without having to first install them globally.
When prompted, choose the following:
- `Yes` when prompted whether to install the React dependencies.
- `Yes` when prompted whether to make changes to the Astro configuration file.
- `Yes` when prompted whether to make changes to `tsconfig.json` file.
Now, let's move on to integrating Unplugin Icons in your Astro application.
## Integrate Unplugin Icons in your Astro project
### Install the Unplugin Icons dependencies
Execute the commands below to install the necessary packages for using Unplugin Icons with React in Astro:
```bash
# unplugin-icons package for Vite compiler
npm i -D unplugin-icons
# @iconify/json package for the icons collection
npm i -D @iconify/json
# @svgr/core and @svgr/plugin-jsx packages for React compatibility
npm i -D @svgr/core @svgr/plugin-jsx
```
The command installs the following libraries:
- `unplugin-icons`: A package to access thousands of icons as components on-demand universally.
- `@iconify/json`: A big collection of open source vector icons, all validated, cleaned up and converted to the same easy to use format.
- `@svgr/core`: A package to transform SVGs into React components.
- `@svgr/plugin-jsx`: A package to transform SVG into JSX.
Further, perform the following additions in `astro.config.mjs` to use the Unplugin Icons integration:
```tsx
// File: astro.config.mjs
import react from "@astrojs/react";
import Icons from "unplugin-icons/vite"; // [!code ++] // [!code focus]
import { defineConfig } from "astro/config";
export default defineConfig({
integrations: [
react(),
vite: { // [!code ++] // [!code focus]
plugins: [ // [!code ++] // [!code focus]
Icons({ // [!code ++] // [!code focus]
jsx: "react", // [!code ++] // [!code focus]
compiler: "jsx", // [!code ++] // [!code focus]
autoInstall: true, // [!code ++] // [!code focus]
}), // [!code ++] // [!code focus]
Icons({ // [!code ++] // [!code focus]
compiler: "astro", // [!code ++] // [!code focus]
autoInstall: true, // [!code ++] // [!code focus]
}), // [!code ++] // [!code focus]
], // [!code ++] // [!code focus]
}, // [!code ++] // [!code focus]
],
});
```
As learnt from a [GitHub issue](https://github.com/unplugin/unplugin-icons/issues/253), it is wise to use both compiler modes, i.e. with React and Astro. This allows the usage of Unplugin Icons in both React and Astro components in your Astro application.
### Create Type Definitions for Unplugin Icons
To make sure that you can leverage the type definitions of the Unplugin Icons using React in Astro, you would want to globally define such specific Icon imports as React component imports.
To do so, update the `env.d.ts` in the `src` directory with the following code:
```tsx
///