> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/react-icons/react-icons/llms.txt
> Use this file to discover all available pages before exploring further.

# Adding Icon Sets

> Complete guide to adding new icon libraries to React Icons

# Adding New Icon Sets

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

## Before You Start

<Warning>
  Before proposing a new icon set, check the [New Icon Set Discussions](https://github.com/react-icons/react-icons/discussions/categories/new-icon-set) to see if it's already been requested.
</Warning>

### Requirements Checklist

<Steps>
  <Step title="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)
  </Step>

  <Step title="SVG source files">
    The icon pack must provide:

    * SVG source files (not just icon fonts)
    * Publicly accessible repository
    * Stable file structure
    * Consistent naming convention
  </Step>

  <Step title="Quality and scope">
    The icon pack should:

    * Have at least 50+ icons
    * Be actively maintained
    * Have a reasonable use case
    * Not duplicate existing packs
  </Step>
</Steps>

## Proposing a New Icon Set

<Steps>
  <Step title="Create a discussion">
    Start a [new discussion](https://github.com/react-icons/react-icons/discussions/new?category=new-icon-set) 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
  </Step>

  <Step title="Get community feedback">
    Wait for feedback from maintainers and community. They may:

    * Approve the addition
    * Request changes
    * Decline if it doesn't meet requirements
  </Step>

  <Step title="Prepare to implement">
    Once approved, you can implement the addition yourself or wait for a maintainer to do it.
  </Step>
</Steps>

## Implementation Guide

### Icon Definition Structure

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

```typescript theme={null}
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

<Steps>
  <Step title="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**   |
  </Step>

  <Step title="Add the definition">
    Edit `packages/react-icons/src/icons/index.ts` and add your pack:

    ```typescript theme={null}
    {
      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
      },
    }
    ```
  </Step>

  <Step title="Determine the formatter function">
    The formatter function transforms SVG filenames to React component names:

    ```typescript theme={null}
    // 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 })}`
    ```
  </Step>

  <Step title="Handle multiple variants (optional)">
    If the icon pack has variants (solid, outline, etc.), add separate content entries:

    ```typescript theme={null}
    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}`,
      },
    ]
    ```
  </Step>
</Steps>

### Adding an NPM-Based Icon Pack

Some icon packs are distributed via npm:

```typescript theme={null}
{
  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",
}
```

<Note>
  For npm packages, omit the `source` field and install the package as a devDependency in `package.json`.
</Note>

## Fetching and Building

<Steps>
  <Step title="Fetch the icons">
    ```bash theme={null}
    cd packages/react-icons
    yarn fetch
    ```

    This clones the repository and copies SVG files to `icons/your-pack/`.
  </Step>

  <Step title="Validate the icons">
    ```bash theme={null}
    yarn check
    ```

    This verifies:

    * All SVG files are valid
    * No duplicate icon names
    * File paths are correct
  </Step>

  <Step title="Build the components">
    ```bash theme={null}
    yarn build
    ```

    This generates React components in `your-prefix/`.
  </Step>

  <Step title="Test the icons">
    ```bash theme={null}
    cd ../demo
    yarn start
    ```

    Create a test component:

    ```jsx theme={null}
    import { XxHome, XxUser } from "react-icons/xx";

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

## Special Configurations

### Multi-Color Icons

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

```typescript theme={null}
{
  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:

```typescript theme={null}
{
  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:

```typescript theme={null}
{
  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

<Steps>
  <Step title="Add to README.md">
    Update the icon library table in `README.md`:

    ```markdown theme={null}
    | [Example Icons](https://example.com/) | [MIT](https://...) | 1.0.0 | 250 |
    ```
  </Step>

  <Step title="Update icon count">
    Count the generated icons:

    ```bash theme={null}
    ls packages/react-icons/xx/*.js | wc -l
    ```
  </Step>

  <Step title="Document import pattern">
    Add an example to the documentation:

    ```jsx theme={null}
    import { XxHome } from "react-icons/xx";
    ```
  </Step>
</Steps>

## Submitting Your Changes

<Steps>
  <Step title="Create a pull request">
    Follow the [Contributing guide](/advanced/contributing) to submit your changes.
  </Step>

  <Step title="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)
  </Step>

  <Step title="Wait for review">
    A maintainer will review your PR and may request changes.
  </Step>
</Steps>

## Icon Naming Best Practices

<Tip>
  Follow these guidelines for consistent icon naming:
</Tip>

* 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

<AccordionGroup>
  <Accordion title="SVG files not found">
    Verify the file path in your icon definition:

    ```typescript theme={null}
    files: path.resolve(
      __dirname,
      "../../icons/your-pack/svg/*.svg"  // Check this path
    )
    ```

    Run `ls icons/your-pack/svg/*.svg` to verify files exist.
  </Accordion>

  <Accordion title="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:

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

  <Accordion title="Icons render incorrectly">
    Try enabling SVGO processing:

    ```typescript theme={null}
    processWithSVGO: true,
    ```

    Or for multi-color icons, disable it:

    ```typescript theme={null}
    multiColor: true,
    ```
  </Accordion>

  <Accordion title="Build fails with memory error">
    Increase Node.js heap size:

    ```bash theme={null}
    export NODE_OPTIONS="--max-old-space-size=4096"
    yarn build
    ```
  </Accordion>
</AccordionGroup>

## Examples from Existing Packs

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

<Tabs>
  <Tab title="Font Awesome">
    ```typescript theme={null}
    {
      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",
      },
    }
    ```
  </Tab>

  <Tab title="Heroicons">
    ```typescript theme={null}
    {
      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}`,
        },
      ],
    }
    ```
  </Tab>

  <Tab title="Flat Color Icons">
    ```typescript theme={null}
    {
      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
        },
      ],
    }
    ```
  </Tab>
</Tabs>

## Next Steps

<CardGroup cols={2}>
  <Card title="Contributing" icon="code-pull-request" href="/advanced/contributing">
    Learn how to submit your changes
  </Card>

  <Card title="Building from Source" icon="hammer" href="/advanced/building-from-source">
    Build and test your icon pack
  </Card>
</CardGroup>