Skip to content
Astro Iconset

Configuration Reference

Configure the icon integration

Section titled “Configure the icon integration”

Pass options to icon({ … }) in astro.config.mjs:

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


export default defineConfig({
  integrations: [
    icon({ /* options */ })
  ]
});

All options are optional. Defaults are noted per option below.

include

Section titled “include”

Type: Record<string, string[]>
Default: {} (all installed @iconify-json/* icons are included)

Filter which Iconify icons to include in the final server bundle. Only relevant for output: 'server' or output: 'hybrid' — static builds resolve everything at build time.

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


export default defineConfig({
  integrations: [
    icon({
      include: {
        // Include only these `mdi` icons in the bundle
        mdi: ["account", "account-plus", "account-minus"],
        // Or include an entire set (can be large):
        // mdi: ['*'],
      },
    }),
  ],
});

iconDir

Section titled “iconDir”

Type: string | string[]
Default: "src/icons"

The directory (or directories) from which local SVG files are loaded. Files are referenced by their path relative to this directory, without the .svg extension.

Single directory:

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


export default defineConfig({
  integrations: [
    icon({
      iconDir: "src/assets/icons",
    }),
  ],
});

Multiple directories (merged into the same local set — duplicate file names across folders cause a build error):

icon({
  iconDir: ["src/icons", "src/assets/icons"],
});

iconDirs

Section titled “iconDirs”

Type: Record<string, string>
Default: {} (no named directories)

Map prefix names to directories. Each icon in a named directory is referenced as prefix:name instead of just name. Useful for avoiding name collisions when mixing icon sets from multiple folders.

icon({
  iconDirs: {
    brand: "src/brand-icons",
    ui: "src/ui-icons",
  },
});

Reference icons with their prefix:

<Icon name="brand:logo" />
<Icon name="ui:menu" />

To replace the default local (unprefixed) directory with a named one, set iconDirs.local:

icon({
  iconDirs: {
    local: "src/my-icons", // replaces the default src/icons
    brand: "src/brand-icons",
  },
});

svgoOptions

Section titled “svgoOptions”

Type: Config (SVGO config object)
Default: SVGO runs with preset-default — removes metadata, comments, and redundant attributes

Override the SVGO configuration used to optimize local .svg files at build time. See the SVGO configuration docs for all available plugins and options.

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


export default defineConfig({
  integrations: [
    icon({
      svgoOptions: {
        multipass: true,
        plugins: [
          {
            name: "preset-default",
            params: {
              overrides: {
                // Customize a default plugin option
                inlineStyles: {
                  onlyMatchedOnce: false,
                },
                // Or disable a default plugin
                removeDoctype: false,
              },
            },
          },
          // Convert hard-coded fill/stroke to currentColor so CSS color works
          {
            name: "convertColors",
            params: { currentColor: true },
          },
        ],
      },
    }),
  ],
});