0
# Lucide React
1

2
Lucide React is a comprehensive icon library package for React applications that provides SVG icons as tree-shakable React components. It offers a complete implementation of the Lucide icon collection with customizable styling, sizing, and color properties, designed for maximum performance and flexibility with zero dependencies beyond React.
3

4
## Package Information
5

6
- **Package Name**: lucide-react
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install lucide-react`
10

11
## Core Imports
12

13
```typescript
14
import { Camera, Grid, Pen } from "lucide-react";
15
import { Icon } from "lucide-react";
16
import { createLucideIcon } from "lucide-react";
17
import { icons } from "lucide-react";
18
```
19

20
For CommonJS:
21

22
```javascript
23
const { Camera, Grid, Pen, Icon } = require("lucide-react");
24
```
25

26
Dynamic imports:
27

28
```typescript
29
import { DynamicIcon, iconNames } from "lucide-react/dynamic";
30
```
31

32
## Basic Usage
33

34
```typescript
35
import { Camera, Grid, Pen } from "lucide-react";
36

37
// Basic icon usage
38
const App = () => {
39
  return (
40
    <div>
41
      <Camera />
42
      <Grid size={32} color="blue" />
43
      <Pen strokeWidth={3} className="my-icon" />
44
    </div>
45
  );
46
};
47
```
48

49
## Architecture
50

51
Lucide React is built around several key components:
52

53
- **Icon Components**: Individual icon components (e.g., `Camera`, `Grid`) created from SVG data
54
- **Base Icon Component**: Core `Icon` component that renders SVG from icon node data
55
- **Dynamic Loading**: `DynamicIcon` component for runtime icon selection by name
56
- **Icon Factory**: `createLucideIcon` function for creating new icon components
57
- **Type System**: Complete TypeScript definitions with `LucideProps` and `IconNode` types
58
- **Tree-shaking**: ES modules structure ensuring only imported icons are bundled
59

60
## Capabilities
61

62
### Static Icon Components
63

64
Individual React components for each Lucide icon, optimized for tree-shaking and static imports. Perfect for when you know which icons you need at build time.
65

66
```typescript { .api }
67
type LucideIcon = ForwardRefExoticComponent<
68
  Omit<LucideProps, 'ref'> & RefAttributes<SVGSVGElement>
69
>;
70

71
interface LucideProps extends ElementAttributes {
72
  size?: string | number;
73
  absoluteStrokeWidth?: boolean;
74
}
75
```
76

77
[Static Icons](./static-icons.md)
78

79
### Dynamic Icon Loading
80

81
Runtime icon loading system for displaying icons based on string names. Useful for CMS-driven applications or when icon selection is determined at runtime.
82

83
```typescript { .api }
84
function DynamicIcon(props: DynamicIconProps): JSX.Element;
85

86
interface DynamicIconProps extends LucideProps {
87
  name: IconName;
88
  fallback?: () => JSX.Element | null;
89
}
90

91
type IconName = keyof typeof dynamicIconImports;
92
const iconNames: Array<IconName>;
93
const dynamicIconImports: Record<string, () => Promise<DynamicIconModule>>;
94

95
interface DynamicIconModule {
96
  default: LucideIcon;
97
  __iconNode: IconNode;
98
}
99
```
100

101
[Dynamic Icons](./dynamic-icons.md)
102

103
### Custom Icon Creation
104

105
System for creating custom icon components from icon data, supporting Lucide Lab icons and custom SVG definitions.
106

107
```typescript { .api }
108
function Icon(props: IconComponentProps): JSX.Element;
109
function createLucideIcon(iconName: string, iconNode: IconNode): LucideIcon;
110

111
interface IconComponentProps extends LucideProps {
112
  iconNode: IconNode;
113
}
114

115
type IconNode = [elementName: SVGElementType, attrs: Record<string, string>][];
116
```
117

118
[Custom Icons](./custom-icons.md)
119

120
## Types
121

122
```typescript { .api }
123
import type { SVGProps, ForwardRefExoticComponent, RefAttributes } from 'react';
124
type SVGElementType =
125
  | 'circle'
126
  | 'ellipse' 
127
  | 'g'
128
  | 'line'
129
  | 'path'
130
  | 'polygon'
131
  | 'polyline'
132
  | 'rect';
133

134
type IconNode = [elementName: SVGElementType, attrs: Record<string, string>][];
135

136
type SVGAttributes = Partial<SVGProps<SVGSVGElement>>;
137
type ElementAttributes = RefAttributes<SVGSVGElement> & SVGAttributes;
138

139
interface LucideProps extends ElementAttributes {
140
  size?: string | number;
141
  absoluteStrokeWidth?: boolean;
142
}
143

144
type LucideIcon = ForwardRefExoticComponent<
145
  Omit<LucideProps, 'ref'> & RefAttributes<SVGSVGElement>
146
>;
147
```