lucide-react

lucide-react is the official React implementation of the Lucide icon library, a community-maintained fork of Feather Icons that has grown to over 1,700 consistently designed SVG icons. Each icon ships as an individually importable React component built on a shared forwardRef-based renderer, so bundlers can tree-shake unused icons out of the final build.

The library exposes simple, consistent props for size, stroke width, color, and absolute stroke width, plus a LucideProvider context for setting shared defaults across an entire icon tree. It also ships a DynamicIcon component and a dynamic-imports map for cases where icon names are only known at runtime (e.g. driven by CMS content), keeping static usage fully tree-shakeable while still supporting dynamic lookups.

What You Get

• 1,700+ individually importable icon components, each a small forwardRef-wrapped SVG element
• Consistent props across every icon: size, color, strokeWidth, absoluteStrokeWidth, and standard SVG/className props
• A LucideProvider React context for setting shared icon defaults (size, color, stroke width) app-wide
• DynamicIcon component plus a dynamicIconImports map for rendering icons by string name at runtime
• Full TypeScript typings (LucideIcon, LucideProps, IconNode) generated alongside the icon set
• ESM and CJS builds with sideEffects: false for reliable tree-shaking in Webpack, Rollup, Vite, and Next.js

Common Use Cases

• Adding a consistent icon set to a React or Next.js UI without hand-authoring or hosting SVGs
• Building design systems and component libraries (e.g. shadcn/ui-style stacks) that standardize on one icon language
• Rendering icons by dynamic string name from CMS or config-driven content via DynamicIcon
• Theming icon appearance globally (size/stroke/color) through LucideProvider instead of prop-drilling

Under The Hood

Architecture Every icon in packages/lucide-react/src/icons is a thin wrapper generated by createLucideIcon(name, iconNode) (src/createLucideIcon.ts), which forwards a ref through a shared Icon component (src/Icon.ts) that renders the actual <svg> element and its child SVG tags from a compact IconNode tuple array. Icon reads defaults from defaultAttributes.ts and an optional LucideContext (src/context.ts) set via LucideProvider, so per-icon props always take precedence over provider defaults, which take precedence over library defaults. A parallel DynamicIcon.ts plus generated dynamicIconImports.mjs map lets consumers resolve an icon by string name at runtime for CMS-driven use cases, kept separate from the static exports so default imports remain tree-shakeable. The icon source SVGs and metadata live at the monorepo root (icons/*.svg, icons/*.json) and are code-generated into src/icons and src/aliases by the @lucide/build-icons tool during the package’s build:icons step, then bundled by Rollup (rollup.config.mjs) into ESM/CJS outputs plus .d.ts typings.

Tech Stack The package is TypeScript-first (implementation and tests both in .ts/.tsx), targets React 16.5.1 through 19 as a peer dependency ("react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0"), and is built with Rollup plus rollup-plugin-dts and rollup-plugin-preserve-directives (to retain the 'use client' directive on Icon.ts and context.ts for RSC-aware bundlers). It shares small internal utilities (mergeClasses, toKebabCase, toPascalCase, hasA11yProp) from an internal @lucide/shared workspace package rather than pulling in an external classnames dependency, keeping runtime dependencies at zero. The repo is a pnpm workspace monorepo housing ten framework-specific packages (React, Vue, Svelte, Solid, Preact, Angular, React Native, Astro, static SVG/font, and vanilla lucide) built from one shared icon source of truth.

Code Quality Each of the roughly 1,700 generated icon components is exercised by a shared Vitest suite (tests/createLucideIcon.spec.tsx, tests/Icon.spec.tsx, tests/lucide-react.spec.tsx, tests/DynamicIcon.spec.tsx, tests/context.spec.tsx) using React Testing Library and snapshot assertions (tests/__snapshots__) to catch unintended markup changes, plus a dedicated directives.spec.ts that asserts the 'use client' directive survives the Rollup build. Naming is consistent and mechanically enforced since components are code-generated from icon metadata rather than hand-written, eliminating drift between icons. TypeScript strict typings (IconNode, LucideProps, LucideIcon) are checked via tsc in the build pipeline (pnpm typecheck), and CI (.github/workflows) runs lint, format, and JSON-schema validation (ajv against icon.schema.json) on every change before an icon can be merged.

API Design The public surface is deliberately minimal: import a PascalCase icon component and pass standard SVG props plus size/color/strokeWidth/absoluteStrokeWidth — no custom wrapper markup or CSS required to get a working icon. Every icon shares the exact same prop contract, so switching from one icon to another never requires relearning an API, and the optional LucideProvider context removes repetitive prop-passing for apps that want one global icon style. The separation between static per-icon imports (tree-shakeable) and the opt-in DynamicIcon runtime-lookup path is a thoughtful ergonomics/bundle-size tradeoff exposed explicitly to the consumer rather than hidden behind one do-everything component.