lucide-react

A Lucide icon library package for React applications.

weekly downloads25.7M

versionv0.574.0

licenseISC

categoryui-library

LucideReactFeatherIconsIconSVGFeather IconsFontawesomeFont Awesome

Overview

lucide-react is a React implementation of the Lucide icon library, offering over 1000 professionally designed SVG icons as importable React components. Rather than managing image files or relying on icon fonts, developers import icons directly into their components and render them as inline SVGs with full customization capabilities through props.

The package emerged from a fork of the Feather Icons project, addressing maintenance concerns and expanding the icon set while maintaining a consistent design language. It solves the common problem of icon management in React applications by treating each icon as a first-class component, enabling type-safe imports, dynamic styling, and optimal bundle sizes through automatic tree-shaking.

With over 25 million weekly downloads, lucide-react has become a standard choice for React developers who need a comprehensive, actively maintained icon library. The package is particularly popular in design systems, component libraries, and applications that require consistent iconography without the overhead of font-based solutions or manual SVG management.

The library prioritizes developer experience with zero configuration setup, TypeScript support out of the box, and a prop-based API that feels native to React. All icons are optimized for performance, compressed for minimal file size, and designed to work seamlessly with modern build tools like Vite, Next.js, and Create React App.

Quick Start

typescript

import { useState } from 'react';
import { Search, X, Heart, ShoppingCart, Menu } from 'lucide-react';

function ProductCard({ product }) {
  const [isFavorited, setIsFavorited] = useState(false);
  const [quantity, setQuantity] = useState(0);

  return (
    <div className="product-card">
      <div className="product-header">
        <h3>{product.name}</h3>
        <button 
          onClick={() => setIsFavorited(!isFavorited)}
          aria-label="Toggle favorite"
        >
          <Heart 
            size={20}
            fill={isFavorited ? 'red' : 'none'}
            color={isFavorited ? 'red' : 'gray'}
            strokeWidth={2}
          />
        </button>
      </div>
      
      <p className="price">${product.price}</p>
      
      <div className="actions">
        {quantity > 0 ? (
          <div className="cart-controls">
            <button onClick={() => setQuantity(q => q - 1)}>
              <X size={16} />
            </button>
            <span>{quantity} in cart</span>
            <ShoppingCart size={18} color="green" />
          </div>
        ) : (
          <button onClick={() => setQuantity(1)}>
            <ShoppingCart size={18} />
            Add to Cart
          </button>
        )}
      </div>
    </div>
  );
}

function SearchBar() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div className="nav-search">
      {isOpen ? (
        <div className="search-expanded">
          <Search size={20} color="#666" />
          <input 
            type="text" 
            placeholder="Search products..."
            autoFocus
          />
          <button onClick={() => setIsOpen(false)}>
            <X size={20} />
          </button>
        </div>
      ) : (
        <button onClick={() => setIsOpen(true)}>
          <Menu size={24} />
        </button>
      )}
    </div>
  );
}

Use Cases

Navigation and UI controls: Using icons like Menu, ChevronDown, X, and Search for navigation bars, dropdown menus, close buttons, and search interfaces. These components integrate directly into React state management for toggling menus or triggering actions.

Form inputs and validation: Displaying CheckCircle, AlertCircle, Info, and Eye icons alongside form fields to indicate validation states, show/hide password toggles, or provide contextual help. The ability to dynamically change color and size based on validation state makes this particularly effective.

Data tables and action buttons: Implementing Edit, Trash2, Download, and MoreVertical icons in table rows or card components for user actions. The consistent sizing and styling helps maintain visual hierarchy across complex interfaces.

Status indicators and badges: Rendering Clock, Check, AlertTriangle, and Loader icons to represent loading states, success confirmations, warnings, or time-based information in dashboards and admin panels.

Social and sharing features: Incorporating Share2, Mail, MessageCircle, and brand-adjacent icons for social sharing buttons, communication features, and user engagement actions without requiring custom SVG assets.

Pros & Cons

Pros

+Tree-shaking support ensures only imported icons are bundled, keeping production builds lean even with access to 1000+ icons
+Component-based architecture integrates naturally with React patterns, supporting props, refs, and standard React event handlers
+Active maintenance with frequent updates, new icon additions, and community-driven feature requests
+Fully customizable through props (size, color, strokeWidth) without CSS conflicts or specificity issues
+TypeScript definitions included by default, providing autocomplete and type safety for icon names and props
+Accessible by default with proper ARIA attributes and screen reader support built into components

Cons

−Bundle size increases linearly with icon count if tree-shaking is misconfigured or disabled in your build tool
−Limited to the Lucide design style—if you need icons with different visual weights or styles, you'll need additional libraries
−No direct SSR optimization for frameworks like Next.js App Router—icons render as client components, potentially causing hydration mismatches if not handled carefully
−Breaking changes occasionally occur between major versions, requiring icon name updates or prop adjustments during upgrades
−Performance can degrade with hundreds of icons rendered simultaneously on a single page, as each is a full React component with its own overhead

Install

bash

npm install lucide-react

bash

pnpm add lucide-react

bash

bun add lucide-react

Overview

Quick Start

typescript

import { useState } from 'react';
import { Search, X, Heart, ShoppingCart, Menu } from 'lucide-react';

function ProductCard({ product }) {
  const [isFavorited, setIsFavorited] = useState(false);
  const [quantity, setQuantity] = useState(0);

  return (
    <div className="product-card">
      <div className="product-header">
        <h3>{product.name}</h3>
        <button 
          onClick={() => setIsFavorited(!isFavorited)}
          aria-label="Toggle favorite"
        >
          <Heart 
            size={20}
            fill={isFavorited ? 'red' : 'none'}
            color={isFavorited ? 'red' : 'gray'}
            strokeWidth={2}
          />
        </button>
      </div>
      
      <p className="price">${product.price}</p>
      
      <div className="actions">
        {quantity > 0 ? (
          <div className="cart-controls">
            <button onClick={() => setQuantity(q => q - 1)}>
              <X size={16} />
            </button>
            <span>{quantity} in cart</span>
            <ShoppingCart size={18} color="green" />
          </div>
        ) : (
          <button onClick={() => setQuantity(1)}>
            <ShoppingCart size={18} />
            Add to Cart
          </button>
        )}
      </div>
    </div>
  );
}

function SearchBar() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div className="nav-search">
      {isOpen ? (
        <div className="search-expanded">
          <Search size={20} color="#666" />
          <input 
            type="text" 
            placeholder="Search products..."
            autoFocus
          />
          <button onClick={() => setIsOpen(false)}>
            <X size={20} />
          </button>
        </div>
      ) : (
        <button onClick={() => setIsOpen(true)}>
          <Menu size={24} />
        </button>
      )}
    </div>
  );
}

Use Cases

Pros & Cons

Pros

+Tree-shaking support ensures only imported icons are bundled, keeping production builds lean even with access to 1000+ icons
+Component-based architecture integrates naturally with React patterns, supporting props, refs, and standard React event handlers
+Active maintenance with frequent updates, new icon additions, and community-driven feature requests
+Fully customizable through props (size, color, strokeWidth) without CSS conflicts or specificity issues
+TypeScript definitions included by default, providing autocomplete and type safety for icon names and props
+Accessible by default with proper ARIA attributes and screen reader support built into components

Cons

−Bundle size increases linearly with icon count if tree-shaking is misconfigured or disabled in your build tool
−Limited to the Lucide design style—if you need icons with different visual weights or styles, you'll need additional libraries
−No direct SSR optimization for frameworks like Next.js App Router—icons render as client components, potentially causing hydration mismatches if not handled carefully
−Breaking changes occasionally occur between major versions, requiring icon name updates or prop adjustments during upgrades
−Performance can degrade with hundreds of icons rendered simultaneously on a single page, as each is a full React component with its own overhead