There is a GitHub discussion on the shadcn/ui repository with over a hundred comments where developers debate a single question: should the default icon library be react-icons or lucide-react? Developers on both sides make reasonable points. Nobody has a clean answer.
That discussion has played out in thousands of Slack channels, Discord servers, and pull request reviews since. It is the most common icon library question in the React ecosystem in 2026 — and it remains underserved because most comparisons either pick a side without data, or treat the two libraries as interchangeable when they are fundamentally different tools built for different purposes.
This is the comparison that should end the debate. Real numbers, real tradeoffs, and a clear decision framework so you can stop re-opening that GitHub discussion.
TL;DR — The Short Answer
Use lucide-react when you are starting a new React or Next.js project, using shadcn/ui, or when bundle size and design consistency matter. Single package install, 5KB for 50 icons, clean API, active maintenance.
Use react-icons when you need icons from multiple design systems in one package (Font Awesome + Material + Heroicons + more), are working in a codebase that already uses it, or are building a prototype where icon variety matters more than bundle optimization.
Never use react-icons as a drop-in replacement for lucide-react — they solve different problems and the bundle cost difference is significant enough to matter in production.
The Download Numbers
Both libraries have massive adoption, but the trajectory tells a clearer story.
lucide-react currently receives over 73 million weekly downloads and is actively gaining ground. npm weekly downloads as of early 2026: Lucide React at approximately 5 million React-specific downloads per week, with lucide-react leading among React-specific icon packages. react-icons also commands significant downloads as the package that aggregates 20+ icon sets into one dependency.
The key context: lucide-react downloads are almost entirely React applications. react-icons downloads include every framework it supports. When you filter to pure React and Next.js project starts — the audience making the lucide vs react-icons decision — lucide-react's growth curve has been steeper every month since mid-2024.
The reason is shadcn/ui. When a developer scaffolds a new shadcn/ui project, every generated component ships with lucide-react imports. The library became the default without anyone making an active choice — which is exactly why the debate keeps resurfacing. Developers who preferred react-icons are now inheriting lucide-react in their shadcn projects and wondering whether to switch everything or keep two icon libraries running.
Bundle Size — The Most Important Difference
This is where the comparison stops being aesthetic and becomes architectural.
Here are real measurements from a Next.js 15 project with Turbopack, showing the gzip bundle delta for importing icons from each library:
The react-icons numbers are not a typo. Importing 10 icons costs the same as importing 200 icons — roughly 81KB. This is not a tree-shaking failure on your end. It is a structural consequence of how react-icons packages its icons.
// Why react-icons Cannot Tree-Shake
react-icons bundles its icon sets as CommonJS modules, not ES modules. Tree-shaking requires ES module format because only ESM gives bundlers the static import graph they need to identify and eliminate unused code at build time. CommonJS exports are determined at runtime — the bundler cannot know ahead of time which icons will be used, so it includes the entire sub-pack.
// This import looks like a named import — it is not tree-shakeable
import { FaHome, FaBell, FaCog } from 'react-icons/fa'
// Result: the entire Font Awesome pack comes along (~81KB gzip)
// lucide-react uses ESM — each icon is a separate module
import { Home, Bell, Settings } from 'lucide-react'
// Result: only those three icons are bundled (~0.5KB each)The workaround is @react-icons/all-files, the ESM-native version of react-icons:
// @react-icons/all-files uses ESM and tree-shakes correctly
import { FaHome } from '@react-icons/all-files/fa/FaHome'
import { FaBell } from '@react-icons/all-files/fa/FaBell'The tradeoff: @react-icons/all-files takes significantly longer to install because it ships every icon as a separate file, and the import paths are more verbose. Most teams who care about bundle size enough to use @react-icons/all-files end up concluding that migrating to lucide-react or a native ESM library is simpler.
API Comparison — Day-to-Day Developer Experience
// Installation
# lucide-react — one package, done npm install lucide-react # react-icons — one package, but with caveats npm install react-icons # If you want ESM tree-shaking: npm install @react-icons/all-files # warning: large install
// Basic Usage
// lucide-react
import { Home, Settings, Bell } from 'lucide-react'
function App() {
return (
<div>
<Home size={24} />
<Settings size={24} color="#6366f1" />
<Bell size={24} strokeWidth={1.5} />
</div>
)
}
// react-icons — Font Awesome set
import { FaHome, FaCog, FaBell } from 'react-icons/fa'
function App() {
return (
<div>
<FaHome size={24} />
<FaCog size={24} color="#6366f1" />
<FaBell size={24} />
</div>
)
}Both APIs are clean. The difference becomes noticeable in three areas:
1. Sizing — lucide-react uses a size prop that sets both width and height. react-icons uses a size prop that sets fontSize on the wrapping span element. For pixel-precise layouts, lucide-react's SVG-native sizing is more predictable and works better with Tailwind's h-* and w-* classes.
// lucide-react — predictable SVG sizing, plays well with Tailwind
<Home size={20} />
<Home className="h-5 w-5" /> // both work identically
// react-icons — size sets font-size on wrapper span, not SVG dimensions directly
<FaHome size={20} />
<FaHome className="h-5 w-5" /> // h-5 w-5 may not size correctly2. Stroke width customization — lucide-react supports a strokeWidth prop on every icon, letting you match your design system's line weight across all icons with a single prop. react-icons icons are pre-rendered at fixed stroke widths because many sets (Font Awesome solid, Material) are filled, not stroked.
// lucide-react — stroke width as a first-class prop
<Home strokeWidth={1} /> // thin, minimal
<Home strokeWidth={2} /> // default
<Home strokeWidth={3} /> // bold, high-contrast
// react-icons — no stroke width control (most icons are fills, not strokes)
<FaHome /> // fixed weight3. TypeScript experience — lucide-react exports a LucideIcon type that makes it trivial to accept any icon as a prop. react-icons has IconType but the ecosystem of components built around it is smaller.
// lucide-react — clean TypeScript prop typing
import type { LucideIcon } from 'lucide-react'
interface ButtonProps {
icon: LucideIcon
label: string
}
function IconButton({ icon: Icon, label }: ButtonProps) {
return (
<button>
<Icon size={16} aria-hidden="true" />
{label}
</button>
)
}
// react-icons — equivalent pattern
import type { IconType } from 'react-icons'
interface ButtonProps {
icon: IconType
label: string
}
function IconButton({ icon: Icon, label }: ButtonProps) {
return (
<button>
<Icon size={16} aria-hidden={true} />
{label}
</button>
)
}Both work. lucide-react's LucideIcon type is slightly better documented in the ecosystem because shadcn/ui components use it extensively.
Icon Count and Variety
This is where react-icons wins decisively, and why many developers are reluctant to leave it.
lucide-react: ~1,500 icons. One consistent design system. All stroke-based, 24px grid, 2px stroke weight. No filled variants (a fill prop was added in recent versions for some icons). No brand icons.
react-icons: 50,000+ icons from 20+ icon sets including:
- →Font Awesome 6 (solid, regular, brands)
- →Material Design Icons
- →Heroicons (outline and solid)
- →Feather Icons
- →Bootstrap Icons
- →Phosphor Icons
- →Ionicons
- →Tabler Icons
- →Ant Design Icons
- →Remix Icon
- →And many more
The react-icons value proposition is that you get every popular icon library through one import syntax. If you need a specific brand logo, a filled variant, a Material Design icon for an Android-feel UI, or a Font Awesome icon that users recognize from a decade of web use — react-icons has it.
The catch: mixing icon sets from react-icons is visually inconsistent. A Font Awesome solid icon next to a Feather outline icon in the same toolbar looks jarring because the design languages are incompatible. If you use react-icons to access everything, you need discipline about which sets you use where.
// This is a common react-icons anti-pattern
import { FaHome } from 'react-icons/fa' // Font Awesome — thick, filled
import { GoSearch } from 'react-icons/go' // Github Octicons — different weight
import { MdSettings } from 'react-icons/md' // Material — different aesthetic
// These three icons will look inconsistent next to each other
<nav>
<FaHome />
<GoSearch />
<MdSettings />
</nav>Lucide's constraint is its strength for UI consistency. One design system, one stroke weight, every icon looks like it was drawn by the same hand.
Design Aesthetic
The visual difference is significant and matters for how your application feels.
lucide-react uses clean, geometric stroke-based icons with rounded line caps and consistent 2px strokes. The aesthetic is modern, minimal, and technical — the same visual language as Linear, Vercel's dashboard, Raycast, and most shadcn/ui-based products. It reads as "developer tool" or "modern SaaS."
react-icons (Font Awesome solid set) uses heavier, filled icons with a more utilitarian aesthetic. Font Awesome icons have been on the web since 2012 and users recognize them immediately — which is both their strength and their weakness. They feel familiar and trustworthy, but they also signal "this was built with standard tools" rather than "this was carefully designed."
react-icons (Heroicons set) via react-icons is visually close to lucide-react and a reasonable middle ground — but you could just install @heroicons/react directly and avoid the react-icons bundle overhead.
If your product's visual identity matters — if you want the interface to feel distinctive and modern rather than generic — lucide-react or a carefully curated single icon set is the right choice. If you are building an internal tool or admin dashboard where recognizability trumps aesthetics, react-icons gives you maximum coverage with minimum decision-making.
The shadcn/ui Question
This is where most of the 2026 debate is happening. shadcn/ui uses lucide-react as its default icon library. Every npx shadcn add command that installs a component with icons will add lucide-react imports to your project.
If you are building with shadcn/ui and also want to use react-icons, you now have two icon libraries running in parallel. This creates three problems.
First, bundle size: you are paying the react-icons baseline cost (81KB) on top of your lucide-react usage. Second, visual consistency: shadcn/ui components use lucide-react icons, and your custom components use react-icons icons — they will not match visually. Third, developer confusion: new team members will encounter two icon systems and have no guidance on which to use where.
The cleanest solution for shadcn/ui projects is to commit to lucide-react for all UI icons and supplement with purpose-specific libraries when lucide genuinely does not have what you need.
// ✅ Clean approach in a shadcn/ui project
// lucide-react for all UI icons
import { Home, Settings, Bell, User, Search } from 'lucide-react'
// Simple Icons for brand logos (MIT license, no bundle bloat from unused brands)
import { SiGithub, SiTwitter } from '@icons-pack/react-simple-icons'
// This way: consistent UI icons, brand icons only where neededSimple Icons is a dedicated brand icon library (2,000+ brand SVGs, MIT license) that gives you brand coverage without pulling in react-icons' entire Font Awesome brands set.
When to Use react-icons
Despite the bundle size concerns, react-icons remains the right choice in specific situations:
Legacy codebases with deep react-icons integration — migrating thousands of icon imports is real work. If the product is stable and performance is not a bottleneck, the migration cost is often not worth it. Use @react-icons/all-files to fix tree-shaking without rewriting imports.
Prototypes and internal tools — when you need icons fast and variety matters more than bundle optimization, react-icons' breadth is genuinely useful. Install it, use whatever icons look right, optimize later if needed.
Projects that specifically need Font Awesome icons — Font Awesome icons have over a decade of user recognition. For interfaces where user familiarity with icon shapes is a feature (enterprise applications, marketing sites targeting non-technical audiences), the Font Awesome aesthetic has real value that a modern stroke-based library cannot replicate.
Projects mixing multiple design systems — if your product intentionally uses Material Design in one section and Heroicons in another (perhaps a mobile-style UI inside a desktop app), react-icons provides a unified import pattern that is easier to manage than installing multiple libraries separately.
When to Use lucide-react
New React or Next.js projects in 2026 — lucide-react should be the default. Single install, excellent tree-shaking, TypeScript-first, active maintenance, and the design aesthetic that matches modern developer tool and SaaS interfaces.
shadcn/ui projects — lucide-react is already a dependency. Using it for all your custom icons keeps the project coherent and avoids a parallel icon system.
Performance-sensitive applications — 5KB for 50 icons versus 81KB is not a marginal difference. On slow mobile connections, that 76KB gap translates to measurable load time.
Design systems and component libraries — the LucideIcon type and consistent API make lucide-react the cleanest choice for a shared component library where icon slots need to be strongly typed and visually consistent.
Applications where stroke weight customization matters — the strokeWidth prop is genuinely useful for accessibility (thicker strokes for high-contrast themes), responsive design (thinner strokes at large sizes, thicker at small sizes), and brand differentiation.
Migration Guide: From react-icons to lucide-react
If you are migrating an existing react-icons codebase to lucide-react, the process is mechanical for the most common icon sets.
Most Font Awesome and Feather icons in react-icons have direct equivalents in lucide-react with predictable naming:
// react-icons (Font Awesome) → lucide-react equivalents // FaHome → Home // FaUser → User // FaCog / FaGear → Settings // FaSearch / FaMagnifyingGlass → Search // FaBell → Bell // FaTrash → Trash2 // FaEdit / FaPencil → Pencil // FaCheck → Check // FaTimes / FaXmark → X // FaPlus → Plus // FaMinus → Minus // FaArrowRight → ArrowRight // FaExternalLink → ExternalLink // FaEllipsis → MoreHorizontal // FaEllipsisV → MoreVertical // FaChevronRight → ChevronRight // FaChevronDown → ChevronDown
# Step 1: Install lucide-react npm install lucide-react # Step 2: Find all react-icons imports in your project grep -r "from 'react-icons" src/ --include="*.tsx" --include="*.ts" # Step 3: Replace imports file by file, verifying visual output # Step 4: Remove react-icons once all imports are replaced npm uninstall react-icons
For icons that do not have a direct lucide equivalent — specific brand logos, some specialty icons — keep those specific icons from react-icons while migrating everything else. A temporary mixed state is better than blocking the migration on a handful of obscure icons.