Skip to main content

​
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 Packv4 Versionv5 VersionNotable Changes
Font Awesome 66.4.x6.5.xNew icons added
Lucide0.x5.1.xIcon names may have changed
Tabler Icons2.x3.2.xNew variants added
Phosphor Icons2.0.x2.1.xAdditional icons
Simple Icons11.x12.14.xBrand 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 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:
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

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

Build docs developers (and LLMs) love

Get started for freeTalk to us