Using Unplugin Icons in Next.js: A Step-by-Step Guide

In this guide, you will learn how to use Unplugin Icons in a Next.js application. You will go through the process of setting up a new Next.js project, 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

Table Of Contents

• Create a new Next.js application
• Integrate Unplugin Icons in your Next.js project
  • Install the Unplugin Icons dependencies
  • Include Type Definitions for Unplugin Icons
  • Use Unplugin Icons in the index route
• Build and Test your Next.js application locally

Create a new Next.js application

Let’s get started by creating a new Next.js project. Open your terminal and run the following command:

npx create-next-app@latest my-app

When prompted, choose:

• Yes when prompted to use TypeScript.
• No when prompted to use ESLint.
• Yes when prompted to use Tailwind CSS.
• No when prompted to use src/ directory.
• Yes when prompted to use App Router.
• No when prompted to customize the default import alias (@/*).

Once that is done, move into the project directory and start the app in development mode by executing the following command:

cd my-app
npm run dev

The app should be running on localhost:3000. Now, let’s close the developement server to install Unplugin Icons.

Integrate Unplugin Icons in your Next.js project

Install the Unplugin Icons dependencies

Execute the commands below to install the necessary packages for using Unplugin Icons in Next.js:

# unplugin-icons package for Webpack 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 next.config.mjs to use the Unplugin Icons integration:

import unpluginIcons from 'unplugin-icons/webpack' // [!code ++] // [!code focus]

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack(config) { // [!code ++] // [!code focus]
    config.plugins.push( // [!code ++] // [!code focus]
      unpluginIcons({ // [!code ++] // [!code focus]
        compiler: 'jsx', // [!code ++] // [!code focus]
        jsx: 'react', // [!code ++] // [!code focus]
      }), // [!code ++] // [!code focus]
    ) // [!code ++] // [!code focus]
    return config // [!code ++] // [!code focus]
  }, // [!code ++] // [!code focus]
}

export default nextConfig

Include Type Definitions for Unplugin Icons

To make sure that you can leverage the type definitions of the Unplugin Icons in Next.js, you would want to globally define such specific Icon imports as React component imports. To do so, update the tsconfig.json file with the following code:

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "types": ["unplugin-icons/types/react"], // [!code ++] // [!code focus]
    "jsx": "preserve",
    "incremental": true,
    "paths": {
      "@/*": ["./*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules"]
}

The code above simply marks each import from ~icons to be considered as a React component in your Next.js application.

Use Unplugin Icons in the index route

Finally, import the icon and use it in your Next.js index route with the following code:

import ClockIcon from '~icons/mdi/clock'

export default function Home() {
  return (
    <ClockIcon />
  );
}

The code above imports an icon as a React component in the index route.

You’re all done now!

Build and Test your Next.js application locally

To test the application, prepare a build and run the preview server using the command below:

npm run build && npm run start

Conclusion

In this guide, you learned how to use Unplugin Icons in a Next.js application.

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