Skip to content
Astro Icon

Upgrade to Astro Icon v1

This guide will help you migrate from older versions of astro-icon to astro-icon v1.

There are multiple breaking changes in astro-icon v1 that require changes to your existing code. This guide will outline the steps you must take.

History

Section titled “History”

The original version of astro-icon was built in December 2021, when Astro had not even released a stable v1. Every Astro project was, by definition, a static site. Server-side rendering was not a supported feature and there was no official API for integrations. astro-icon’s architecture reflected the reduced scope that Astro had at the time.

In v1, astro-icon has been refactored to provide a more stable foundation that supports everything Astro v3+ is capable of, including server-side rendering.

Upgrade astro-icon

Section titled “Upgrade astro-icon”

Update your project’s version of astro-icon to the latest version using your package manager.

Terminal window
npm install astro-icon@latest

Breaking Changes

Section titled “Breaking Changes”

Changed: astro-icon is now an integration

Section titled “Changed: astro-icon is now an integration”

In v0, the entire API surface was limited to the Icon and Sprite components.

In v1, astro-icon has become a full-fledged integration.

What should I do?

Section titled “What should I do?”

Update your astro.config.mjs file to include the new astro-icon integration.

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


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

Removed: Remote API service

Section titled “Removed: Remote API service”

In v0, icons were automatically fetched from a custom Astro Icon API, powered internally by Iconify. While this was convenient, missing icons and network latency caused frequent problems.

In v1, icon sets must be installed as a dependency in your project.

What should I do?

Section titled “What should I do?”

Determine the icon sets (previously referred to as a “pack”) used in your project. Install the equivalent @iconify-json/<name> package.

For example, if using the mdi:account and carbon:basketball icons, the mdi and carbon icons must be installed in your project.

Terminal window
npm install @iconify-json/mdi @iconify-json/carbon

Changed: component export location

Section titled “Changed: component export location”

In v0, components were exported directly from the astro-icon package.

In v1, components are exported from the astro-icon/components path.

What should I do?

Section titled “What should I do?”

Update your import statements to reference astro-icon/components.

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

Changed: styling attribute

Section titled “Changed: styling attribute”

In v0, icons used an astro-icon attribute for styling. This was technically invalid HTML.

In v1, icons use the data-icon attribute instead.

What should I do?

Section titled “What should I do?”

Replace any [astro-icon] selectors in your styles with the equivalent [data-icon] selector.

<style>
  [astro-icon] {
  [data-icon] {
    color: blue;
  }
  [astro-icon="annotation"] {
  [data-icon="annotation"] {
    color: red;
  }
</style>

Removed: pack prop

Section titled “Removed: pack prop”

In v0, the Icon component accepted separate pack and name props plus a shorthand pack:name syntax.

In v1, the Icon component only accepts a name prop. Packs are always referenced via the shorthand pack:name syntax.

What should I do?

Section titled “What should I do?”

Update your components to replace the pack prop with the name prop.

<Icon pack="mdi" name="mdi:account" />

Removed: Sprite component

Section titled “Removed: Sprite component”

In v0, the Sprite component was used to generate an SVG spritesheet. This required your entire page to be wrapped in a <Sprite.Provider>.

In v1, the Sprite component has been removed. The Icon component now automatically optimizes itself into an SVG spritesheet when used multiple times on the same page.

What should I do?

Section titled “What should I do?”

Remove the <Sprite.Provider> wrapper from your pages. Replace any references to the Sprite component with the Icon component.

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


 <Sprite.Provider>
  <html>
    <head></head>
    <body>
      <Sprite name="building" />
      <Icon name="building" />
    </body>
 </Sprite.Provider>

Removed: createIconPack utilities

Section titled “Removed: createIconPack utilities”

In v0, the astro-icon/pack module exported a createIconPack utility to create custom local icon packs from JS/TS files.

In v1, the astro-icon/pack module has been removed. Network and custom loaders are no longer supported. All icons must be placed in the src/icons/ directory.

What should I do?

Section titled “What should I do?”

Remove any loaders that used createIconPack. Instead, create a new directory for each icon pack in the src/icons/ directory and add one .svg file for each icon.

Removed: optimize prop

Section titled “Removed: optimize prop”

In v0, the Icon component accepted an optimize prop, but it defaulted to true. This controlled the SVGO optimizations for specific icons.

In v1, the optimize prop has been removed. SVGO optimizations are automatically performed during the build rather than dynamically at runtime.

What should I do?

Section titled “What should I do?”

Remove any usage of the optimize prop. Configure SVGO optimization by passing svgoOptions to the icon() integration instead.

 <Icon name="mdi:account" optimize />
astro.config.mjs
import { defineConfig } from "astro/config";
import icon from "astro-icon";


export default defineConfig({
  integrations: [
    icon({
      svgoOptions: {
        plugins: [
          "preset-default",
          {
            name: "convertColors",
            params: { currentColor: true },
          },
        ],
      },
    }),
  ],
});