> ## 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.

# Migrating from v2 to v3

> Learn how to migrate your React Icons installation from version 2 to version 3

# Migrating from Version 2 to Version 3

Version 3 of React Icons introduced significant improvements including better tree-shaking support and a new import pattern. This guide will help you migrate your codebase smoothly.

## Breaking Changes

<Warning>
  Version 3 introduced breaking changes to the import syntax and removed automatic vertical alignment. Read this guide carefully before upgrading.
</Warning>

### 1. Import Syntax Change

The most significant change in v3 is the new import syntax.

<Tabs>
  <Tab title="v2 (Old)">
    ```jsx theme={null}
    import FaBeer from "react-icons/lib/fa/beer";

    function Question() {
      return (
        <h3>
          Lets go for a <FaBeer />?
        </h3>
      );
    }
    ```
  </Tab>

  <Tab title="v3 (New)">
    ```jsx theme={null}
    import { FaBeer } from "react-icons/fa";

    function Question() {
      return (
        <h3>
          Lets go for a <FaBeer />?
        </h3>
      );
    }
    ```
  </Tab>
</Tabs>

**Key Differences:**

* v2 used default imports from individual icon files
* v3 uses named imports from icon pack modules
* v3 enables better tree-shaking and smaller bundle sizes

### 2. Vertical Alignment Removed

Version 3 removed the automatic `vertical-align: middle` CSS property. You now need to add this manually if needed.

<Steps>
  <Step title="Option 1: Global Inline Styling">
    Use the IconContext to apply vertical alignment globally:

    ```jsx theme={null}
    import { IconContext } from "react-icons";

    <IconContext.Provider value={{ style: { verticalAlign: 'middle' } }}>
      {/* Your app content */}
    </IconContext.Provider>
    ```
  </Step>

  <Step title="Option 2: Global className Styling">
    Apply a CSS class globally:

    ```jsx theme={null}
    import { IconContext } from "react-icons";

    <IconContext.Provider value={{ className: 'react-icons' }}>
      {/* Your app content */}
    </IconContext.Provider>
    ```

    Then in your CSS:

    ```css theme={null}
    .react-icons {
      vertical-align: middle;
    }
    ```
  </Step>

  <Step title="Option 3: Individual Icon Styling">
    Add the style to specific icons:

    ```jsx theme={null}
    import { FaBeer } from "react-icons/fa";

    <FaBeer style={{ verticalAlign: 'middle' }} />
    ```
  </Step>
</Steps>

### 3. TypeScript Support

Version 3 includes native TypeScript support. You can remove the separate type definitions package:

<CodeGroup>
  ```bash npm theme={null}
  npm remove @types/react-icons
  ```

  ```bash yarn theme={null}
  yarn remove @types/react-icons
  ```

  ```bash pnpm theme={null}
  pnpm remove @types/react-icons
  ```
</CodeGroup>

## Migration Steps

<Steps>
  <Step title="Update the package version">
    Update react-icons to version 3 or later:

    <CodeGroup>
      ```bash npm theme={null}
      npm install react-icons@latest
      ```

      ```bash yarn theme={null}
      yarn add react-icons@latest
      ```

      ```bash pnpm theme={null}
      pnpm add react-icons@latest
      ```
    </CodeGroup>
  </Step>

  <Step title="Update import statements">
    Replace all old-style imports with the new syntax. You can use find-and-replace:

    **Find pattern:** `import (\w+) from "react-icons/lib/(\w+)/.*"`

    **Replace with:** `import { $1 } from "react-icons/$2"`

    <Note>
      Depending on your icon usage, you may need to adjust imports manually if you're using multiple icons from the same pack.
    </Note>
  </Step>

  <Step title="Add vertical alignment (if needed)">
    If your design relies on vertical alignment, add it back using one of the methods described above.
  </Step>

  <Step title="Remove TypeScript type definitions">
    If you're using TypeScript, remove the `@types/react-icons` package as v3 includes native type definitions.
  </Step>

  <Step title="Test your application">
    Run your tests and visually verify that icons render correctly:

    ```bash theme={null}
    npm test
    npm run build
    ```
  </Step>
</Steps>

## Common Issues

<AccordionGroup>
  <Accordion title="Bundle size increased after migration">
    This usually happens when you're not using ES6 imports correctly. Make sure you're using named imports:

    ```jsx theme={null}
    // ✅ Correct - tree-shakable
    import { FaBeer, FaCoffee } from "react-icons/fa";

    // ❌ Incorrect - imports entire library
    import * as FontAwesome from "react-icons/fa";
    ```

    See the [Tree-Shaking guide](/core-concepts/tree-shaking) for more details.
  </Accordion>

  <Accordion title="Icons appear misaligned">
    Version 3 removed automatic vertical alignment. Add it back using IconContext or inline styles as described above.
  </Accordion>

  <Accordion title="TypeScript errors after migration">
    Remove the `@types/react-icons` package - v3 includes native TypeScript support and the type definitions may conflict.
  </Accordion>

  <Accordion title="Icons not rendering">
    Make sure you've updated your import statements to use the new syntax. The old import paths will not work in v3.
  </Accordion>
</AccordionGroup>

## Benefits of v3

Upgrading to version 3 provides several benefits:

<CardGroup cols={2}>
  <Card title="Better Tree-Shaking" icon="leaf">
    Dramatically reduced bundle sizes with proper ES6 module support
  </Card>

  <Card title="Native TypeScript" icon="code">
    Built-in type definitions with no external package needed
  </Card>

  <Card title="Simpler Imports" icon="file-import">
    Cleaner import syntax that's easier to read and write
  </Card>

  <Card title="Better Performance" icon="gauge-high">
    Optimized rendering and smaller runtime footprint
  </Card>
</CardGroup>

## Need Help?

If you encounter issues during migration:

<CardGroup cols={2}>
  <Card title="FAQ" icon="question" href="/resources/faq">
    Check common questions and answers
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/resources/troubleshooting">
    Find solutions to common problems
  </Card>
</CardGroup>