Cheatsheet — Lucide

Which package for which stack

Stack	Package	Notes
Plain HTML / no build step	lucide (vanilla)	data-lucide attribute + createIcons(), or lucide-static for zero-JS
React / Next.js	lucide-react	per-icon named imports
Vue 3	lucide-vue-next	per-icon named imports
Svelte	lucide-svelte	per-icon named imports
Solid	lucide-solid	per-icon named imports
Astro	lucide-astro	per-icon named imports, works in .astro files
Preact	lucide-preact	per-icon named imports
React Native	lucide-react-native	requires react-native-svg as a peer dependency
Angular	lucide-angular	provided via an icon module/provider, not raw named imports
No JS runtime at all (email, CMS, static export)	lucide-static	SVG files, sprite, or webfont

Decision rules

• Icon name known ahead of time? → static per-icon import. Only reach for the dynamic-icon-by-name helper when the name is genuinely data-driven (e.g. comes from an API/config) — it costs some tree-shaking.
• Need the icon to always match surrounding text color? → leave color as the default currentColor, control color via CSS on a parent instead of a prop.
• Need a fixed visual stroke thickness across different icon sizes? → set absoluteStrokeWidth={true} (or the equivalent prop per framework), otherwise stroke width scales with size.
• Styling many icons the same way across the app? → set defaults once via the framework's global-styling pattern instead of repeating props on every icon instance.
• No bundler / can't use React-style imports? → lucide-static (SVG/sprite/webfont) over the vanilla createIcons() approach, unless you specifically need currentColor and prop-driven customization, which the vanilla JS package supports and the static webfont/sprite path does not.
• Migrating from Feather Icons? → use the React "migration-from-feather" guide's rename table rather than assuming icon names carry over unchanged.
• Migrating a Lucide major version? → check the framework's "migration" guide and version-1 release notes before bulk-upgrading; prop/behavior changes are called out there, not just icon renames.

Common gotchas

Symptom	Likely cause
Icon renders black instead of inheriting text color	An explicit color was passed, or no ancestor sets a CSS color for currentColor to inherit
Icon looks wrong size at different size values	absoluteStrokeWidth not set, so stroke width is scaling proportionally with size
Whole icon set ends up in the production bundle	Namespace import (import * as icons from ...) instead of named per-icon imports — defeats tree-shaking
data-lucide elements inside a <template> tag never get replaced	createIcons() needs inTemplates: true to reach into template contents
React Native app crashes on an icon component	Missing react-native-svg peer dependency
Icon name changed after upgrading	Check the framework's migration guide and the version-1 release notes for renamed/removed icons