Migrating from v4 to v5

Learn about changes and improvements in React Icons v5

Migrating from Version 4 to Version 5

Version 5 of React Icons is largely compatible with version 4, with some updated icon libraries and minor improvements. Most projects can upgrade with minimal changes.

What’s New in v5

Updated Icon Libraries

Many icon packs have been updated to their latest versions

New Icon Packs

Additional icon libraries have been added

Improved TypeScript

Enhanced type definitions and stricter typing

Performance

Build optimizations and smaller bundle sizes

Breaking Changes

Version 5 maintains backward compatibility with v4 for most use cases. The changes below primarily affect specific icon packs.

Updated Icon Pack Versions

The following icon packs have been updated to newer versions:

Icon Pack	v4 Version	v5 Version	Notable Changes
Font Awesome 6	6.4.x	6.5.x	New icons added
Lucide	0.x	5.1.x	Icon names may have changed
Tabler Icons	2.x	3.2.x	New variants added
Phosphor Icons	2.0.x	2.1.x	Additional icons
Simple Icons	11.x	12.14.x	Brand icon updates

Icon Name Changes

Some icon libraries have renamed or removed certain icons in their updates:

If you’re using Lucide icons, check the Lucide changelog as some icon names may have changed between versions.

Migration Steps

1. Update the package version

   Update react-icons to version 5:

   npm

   npm install react-icons@latest
   
2. Test your application

   Run your test suite to ensure all icons still render:

   npm test
   

   Pay special attention to any tests involving the updated icon packs.

3. Check for icon availability

   If any icons are not rendering, they may have been renamed or removed. Check the specific icon pack’s changelog:

   • Font Awesome 6 Changelog
   • Lucide Releases
   • Tabler Icons Changelog
4. Update TypeScript types (if needed)

   If you have custom type definitions that reference icon components, you may need to update them:

   import { IconType } from "react-icons";
   
   // Your icon type definitions should continue to work
   type IconProps = {
     icon: IconType;
     size?: number;
   };
   
5. Build and deploy

   Build your application and verify everything works:

   npm run build
   

New Features

Additional Icon Libraries

Version 5 maintains support for 30+ icon packs. Check the All Libraries page for the complete list.

Improved Build Performance

Version 5 includes optimizations that may reduce your build times:

# Before (v4)
Build time: 45s

# After (v5)
Build time: 38s

The actual improvement depends on your project size and which icons you’re using.

Enhanced TypeScript Support

TypeScript users benefit from improved type inference:

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

// Better type inference for context values
<IconContext.Provider value={{ 
  color: "blue",  // string type inferred
  size: "2em"     // string | number
}}>
  <FaBeer />
</IconContext.Provider>

Common Issues

Icon not found after upgrade

The icon may have been renamed or removed in the newer version of its pack. Check the icon pack’s changelog and find the new name or a suitable replacement.

// Example: If an icon was renamed
import { LuOldName } from "react-icons/lu";  // ❌ May not exist
import { LuNewName } from "react-icons/lu";  // ✅ Check documentation

Bundle size increased

Ensure you’re using named imports and that your bundler supports tree-shaking:

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

// ❌ Wrong - imports everything
import * as Icons from "react-icons/fa";

See Performance Optimization for more tips.

TypeScript errors

Clear your TypeScript cache and rebuild:

rm -rf node_modules/.cache
npm run build

Rollback if Needed

If you encounter issues, you can temporarily roll back to v4:

npm

npm install react-icons@^4.0.0

Make sure to report any issues on the GitHub repository to help improve future releases.

Next Steps

Changelog

View detailed version history

FAQ

Common questions and answers