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

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

1. Import Syntax Change

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

v2 (Old)

import FaBeer from "react-icons/lib/fa/beer";

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

v3 (New)

import { FaBeer } from "react-icons/fa";

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

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.

1. Option 1: Global Inline Styling

   Use the IconContext to apply vertical alignment globally:

   import { IconContext } from "react-icons";
   
   <IconContext.Provider value={{ style: { verticalAlign: 'middle' } }}>
     {/* Your app content */}
   </IconContext.Provider>
   
2. Option 2: Global className Styling

   Apply a CSS class globally:

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

   Then in your CSS:

   .react-icons {
     vertical-align: middle;
   }
   
3. Option 3: Individual Icon Styling

   Add the style to specific icons:

   import { FaBeer } from "react-icons/fa";
   
   <FaBeer style={{ verticalAlign: 'middle' }} />
   

3. TypeScript Support

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

npm

npm remove @types/react-icons

Migration Steps

1. Update the package version

   Update react-icons to version 3 or later:

   npm

   npm install react-icons@latest
   
2. 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"

   Depending on your icon usage, you may need to adjust imports manually if you’re using multiple icons from the same pack.

3. Add vertical alignment (if needed)

   If your design relies on vertical alignment, add it back using one of the methods described above.

4. Remove TypeScript type definitions

   If you’re using TypeScript, remove the @types/react-icons package as v3 includes native type definitions.

5. Test your application

   Run your tests and visually verify that icons render correctly:

   npm test
   npm run build
   

Common Issues

Bundle size increased after migration

This usually happens when you’re not using ES6 imports correctly. Make sure you’re using named imports:

// ✅ 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 for more details.

Icons appear misaligned

Version 3 removed automatic vertical alignment. Add it back using IconContext or inline styles as described above.

TypeScript errors after migration

Remove the @types/react-icons package - v3 includes native TypeScript support and the type definitions may conflict.

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.

Benefits of v3

Upgrading to version 3 provides several benefits:

Better Tree-Shaking

Dramatically reduced bundle sizes with proper ES6 module support

Native TypeScript

Built-in type definitions with no external package needed

Simpler Imports

Cleaner import syntax that’s easier to read and write

Better Performance

Optimized rendering and smaller runtime footprint

Need Help?

If you encounter issues during migration:

FAQ

Check common questions and answers

Troubleshooting

Find solutions to common problems