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
```