Using Unplugin Icons in Astro with React: A Step-by-Step Guide

In this guide, you will learn how to use 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 18 or later

Create a new Astro application
Integrate React in your Astro project
Integrate Unplugin Icons in your Astro project
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:

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 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:

cd my-app
npm run dev

The app should be running on 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:

npx astro add react

npx allows us to execute npm packages binaries without having to first install it globally.

When prompted, choose the following:

Yes when prompted whether to install the React dependencies.
Yes when prompted whether to make changes to 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:

# 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:

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, 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:

/// <reference types="astro/client" />

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<SVGSVGElement>) => 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:

---
import MdiAlarmOff from "virtual:icons/mdi/alarm-off";  // [!code ++] // [!code focus]
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="viewport" content="width=device-width" />
    <meta name="generator" content={Astro.generator} />
    <title>Astro</title>
  </head>
  <body>
    <h1>Astro</h1>
    <MdiAlarmOff client:load /> // [!code ++] // [!code focus]
  </body>
</html>

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:

npm run build && npm run preview

Conclusion

In this guide, you learned how to use Unplugin Icons with React in an Astro application.

If you have any questions or comments, feel free to reach out to me on Twitter.