Adding New Icon Sets

React Icons supports adding new icon libraries. This guide explains the complete process from proposal to integration.

Before You Start

Before proposing a new icon set, check the New Icon Set Discussions to see if it’s already been requested.

Requirements Checklist

License compatibility

The icon pack must have an open-source license:

✅ MIT
✅ Apache 2.0
✅ CC BY 4.0 / CC BY-SA 3.0
✅ ISC
✅ SIL OFL 1.1
❌ Proprietary licenses
❌ GPL (copyleft conflicts with MIT)

SVG source files

The icon pack must provide:

SVG source files (not just icon fonts)
Publicly accessible repository
Stable file structure
Consistent naming convention

Quality and scope

The icon pack should:

Have at least 50+ icons
Be actively maintained
Have a reasonable use case
Not duplicate existing packs

Proposing a New Icon Set

Create a discussion

Start a new discussion with:Include:

Icon pack name and website
License type and link
Number of icons
Repository URL
Use case / why it should be added
Example icons or screenshot

Get community feedback

Wait for feedback from maintainers and community. They may:

Approve the addition
Request changes
Decline if it doesn’t meet requirements

Prepare to implement

Once approved, you can implement the addition yourself or wait for a maintainer to do it.

Implementation Guide

Icon Definition Structure

Icon packs are defined in packages/react-icons/src/icons/index.ts. Here’s the structure:

export const icons: IconDefinition[] = [
  {
    id: "prefix",                    // Unique 2-4 letter prefix
    name: "Icon Pack Name",          // Full display name
    contents: [                      // Icon file groups
      {
        files: "path/to/*.svg",      // Glob pattern or array
        formatter: (name) => `PrefixIconName`,  // Naming function
        processWithSVGO: true,       // Optional: SVGO optimization
        multiColor: false,           // Optional: preserve colors
      },
    ],
    projectUrl: "https://...",       // Official website
    license: "MIT",                  // License type
    licenseUrl: "https://...",       // License file URL
    source: {                        // Source repository (optional)
      type: "git",
      localName: "repo-name",
      remoteDir: "svg/",
      url: "https://github.com/...",
      branch: "main",
      hash: "commit-hash",
    },
  },
];

Adding a Git-Based Icon Pack

Choose a prefix

Select a unique 2-4 letter prefix that doesn’t conflict with existing packs:

Prefix	Icon Pack
`Fa`	Font Awesome
`Md`	Material Design
`Hi`	Heroicons
`Bs`	Bootstrap
`Lu`	Lucide
`Xx`	Your Pack

Add the definition

Edit packages/react-icons/src/icons/index.ts and add your pack:

{
  id: "xx",
  name: "Example Icons",
  contents: [
    {
      files: path.resolve(
        __dirname,
        "../../icons/example-icons/svg/*.svg"
      ),
      formatter: (name) => `Xx${camelcase(name, { pascalCase: true })}`,
    },
  ],
  projectUrl: "https://example-icons.com/",
  license: "MIT",
  licenseUrl: "https://github.com/owner/example-icons/blob/main/LICENSE",
  source: {
    type: "git",
    localName: "example-icons",
    remoteDir: "svg/",
    url: "https://github.com/owner/example-icons.git",
    branch: "main",
    hash: "abc123def456...",  // Latest commit hash
  },
}

Determine the formatter function

The formatter function transforms SVG filenames to React component names:

// Example: arrow-left.svg → XxArrowLeft
formatter: (name) => `Xx${camelcase(name, { pascalCase: true })}`

// Example: solid/check.svg → XxSolidCheck
formatter: (name, file) => {
  const variant = file.includes('/solid/') ? 'Solid' : '';
  return `Xx${variant}${camelcase(name, { pascalCase: true })}`;
}

// Example: Remove prefix: bx-home.svg → XxHome
formatter: (name) => `Xx${camelcase(name.replace(/^bx-/, ''), { pascalCase: true })}`

Handle multiple variants (optional)

If the icon pack has variants (solid, outline, etc.), add separate content entries:

contents: [
  {
    files: path.resolve(__dirname, "../../icons/example/solid/*.svg"),
    formatter: (name) => `Xx${name}`,
  },
  {
    files: path.resolve(__dirname, "../../icons/example/outline/*.svg"),  
    formatter: (name) => `XxOutline${name}`,
  },
]

Adding an NPM-Based Icon Pack

Some icon packs are distributed via npm:

{
  id: "io",
  name: "Ionicons 4",
  contents: [
    {
      files: path.resolve(
        path.dirname(require.resolve("ionicons")),
        "collection/icon/svg/*.svg"
      ),
      formatter: (name) => `Io${name}`,
    },
  ],
  projectUrl: "https://ionicons.com/",
  license: "MIT",
  licenseUrl: "https://github.com/ionic-team/ionicons/blob/master/LICENSE",
}

For npm packages, omit the source field and install the package as a devDependency in package.json.

Fetching and Building

Fetch the icons

cd packages/react-icons
yarn fetch

This clones the repository and copies SVG files to icons/your-pack/.

Validate the icons

yarn check

This verifies:

All SVG files are valid
No duplicate icon names
File paths are correct

Build the components

yarn build

This generates React components in your-prefix/.

Test the icons

cd ../demo
yarn start

Create a test component:

import { XxHome, XxUser } from "react-icons/xx";

function Test() {
  return (
    <div>
      <XxHome size={32} />
      <XxUser size={32} />
    </div>
  );
}

Special Configurations

Multi-Color Icons

Some icon packs use multiple colors (e.g., Flat Color Icons). Preserve colors:

{
  id: "fc",
  name: "Flat Color Icons",
  contents: [
    {
      files: path.resolve(__dirname, "../../icons/flat-color-icons/svg/*.svg"),
      formatter: (name) => `Fc${name}`,
      multiColor: true,  // ✅ Preserves fill colors
    },
  ],
}

SVGO Optimization

Some SVGs need optimization with SVGO:

{
  files: path.resolve(__dirname, "../../icons/material-design/svg/*.svg"),
  formatter: (name) => `Md${name}`,
  processWithSVGO: true,  // ✅ Run SVGO optimization
}

Dynamic File Selection

For complex directory structures, use a function:

{
  files: async () => {
    const normalIcons = await glob("icons/pack/normal/*.svg");
    const specialIcons = await glob("icons/pack/special/*.svg");
    return [...normalIcons, ...specialIcons.filter(notInNormal)];
  },
  formatter: (name, file) => `Xx${name}`,
}

Updating the Documentation

Add to README.md

Update the icon library table in README.md:

| [Example Icons](https://example.com/) | [MIT](https://...) | 1.0.0 | 250 |

Update icon count

Count the generated icons:

ls packages/react-icons/xx/*.js | wc -l

Document import pattern

Add an example to the documentation:

import { XxHome } from "react-icons/xx";

Submitting Your Changes

Create a pull request

Follow the Contributing guide to submit your changes.

Include in PR description

Icon pack name and website
Number of icons added
License information
Screenshots of example icons
Link to the discussion (if applicable)

Wait for review

A maintainer will review your PR and may request changes.

Icon Naming Best Practices

Follow these guidelines for consistent icon naming:

Use PascalCase: XxArrowLeft not xxarrowleft
Include prefix: XxHome not Home
Be descriptive: XxArrowLeft not XxAl
Group variants: XxOutlineHome, XxSolidHome
Avoid special characters: Replace with camelCase

Common Issues

SVG files not found

Verify the file path in your icon definition:

files: path.resolve(
  __dirname,
  "../../icons/your-pack/svg/*.svg"  // Check this path
)

Run ls icons/your-pack/svg/*.svg to verify files exist.

Duplicate icon names

Icon names must be unique within a pack. Check for:

Files with the same name in different directories
Formatter generating the same name for different files

Use variant prefixes to differentiate:

formatter: (name, file) => {
  const variant = file.includes('outline') ? 'Outline' : 'Solid';
  return `Xx${variant}${name}`;
}

Icons render incorrectly

Try enabling SVGO processing:

processWithSVGO: true,

Or for multi-color icons, disable it:

multiColor: true,

Build fails with memory error

Increase Node.js heap size:

export NODE_OPTIONS="--max-old-space-size=4096"
yarn build

Examples from Existing Packs

Learn from existing icon packs in src/icons/index.ts:

Font Awesome
Heroicons
Flat Color Icons

{
  id: "fa6",
  name: "Font Awesome 6",
  contents: [
    {
      files: path.resolve(
        __dirname,
        "../../icons/fontawesome-6/svgs/+(brands|solid)/*.svg"
      ),
      formatter: (name) => `Fa${name}`,
    },
    {
      files: path.resolve(
        __dirname,
        "../../icons/fontawesome-6/svgs/regular/*.svg"
      ),
      formatter: (name) => `FaReg${name}`,
    },
  ],
  source: {
    type: "git",
    url: "https://github.com/FortAwesome/Font-Awesome.git",
    branch: "6.x",
    hash: "840c215f894f429b26b8c1402a65da835dc5a450",
  },
}

{
  id: "hi2",
  name: "Heroicons 2",
  contents: [
    {
      files: path.resolve(
        __dirname,
        "../../icons/heroicons-2/optimized/24/solid/*.svg"
      ),
      formatter: (name) => `Hi${name}`,
    },
    {
      files: path.resolve(
        __dirname,
        "../../icons/heroicons-2/optimized/24/outline/*.svg"
      ),
      formatter: (name) => `HiOutline${name}`,
    },
    {
      files: path.resolve(
        __dirname,
        "../../icons/heroicons-2/optimized/20/solid/*.svg"
      ),
      formatter: (name) => `HiMini${name}`,
    },
  ],
}

{
  id: "fc",
  name: "Flat Color Icons",
  contents: [
    {
      files: path.resolve(
        __dirname,
        "../../icons/flat-color-icons/svg/*.svg"
      ),
      formatter: (name) => `Fc${name}`,
      multiColor: true,  // Preserve original colors
    },
  ],
}

Migration

Advanced

Resources

Adding Icon Sets

Adding New Icon Sets

Before You Start

Requirements Checklist

Proposing a New Icon Set

Implementation Guide

Icon Definition Structure

Adding a Git-Based Icon Pack

Adding an NPM-Based Icon Pack

Fetching and Building

Special Configurations

Multi-Color Icons

SVGO Optimization

Dynamic File Selection

Updating the Documentation

Submitting Your Changes

Icon Naming Best Practices

Common Issues

Examples from Existing Packs

Next Steps

Contributing

Building from Source

​Adding New Icon Sets

​Before You Start

​Requirements Checklist

​Proposing a New Icon Set

​Implementation Guide

​Icon Definition Structure

​Adding a Git-Based Icon Pack

​Adding an NPM-Based Icon Pack

​Fetching and Building

​Special Configurations

​Multi-Color Icons

​SVGO Optimization

​Dynamic File Selection

​Updating the Documentation

​Submitting Your Changes

​Icon Naming Best Practices

​Common Issues

​Examples from Existing Packs

​Next Steps

Contributing

Building from Source

Adding New Icon Sets

Before You Start

Requirements Checklist

Proposing a New Icon Set

Implementation Guide

Icon Definition Structure

Adding a Git-Based Icon Pack

Adding an NPM-Based Icon Pack

Fetching and Building

Special Configurations

Multi-Color Icons

SVGO Optimization

Dynamic File Selection

Updating the Documentation

Submitting Your Changes

Icon Naming Best Practices

Common Issues

Examples from Existing Packs

Next Steps