0
# @medusajs/icons
1

2
@medusajs/icons is a comprehensive React icon library containing 388 auto-generated SVG icon components used in Medusa's design system. The icons are automatically generated from Figma designs using @medusajs/toolbox and provide a consistent, type-safe interface for incorporating scalable vector icons into React applications.
3

4
## Package Information
5

6
- **Package Name**: @medusajs/icons
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @medusajs/icons`
10

11
## Core Imports
12

13
```typescript
14
import { Check, ArrowRight, User } from "@medusajs/icons";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { Check, ArrowRight, User } = require("@medusajs/icons");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { Check, ArrowRight, User } from "@medusajs/icons";
27

28
function MyComponent() {
29
  return (
30
    <div>
31
      {/* Basic usage with default styling */}
32
      <Check />
33
      <ArrowRight />
34
      <User />
35
      
36
      {/* Custom color */}
37
      <Check color="red" />
38
      <ArrowRight color="#3b82f6" />
39
      
40
      {/* With standard SVG attributes */}
41
      <User className="icon-large" onClick={() => console.log('clicked')} />
42
      
43
      {/* All icons use currentColor by default for theme integration */}
44
      <div style={{ color: 'blue' }}>
45
        <Check /> {/* Will be blue */}
46
      </div>
47
    </div>
48
  );
49
}
50
```
51

52
## Architecture
53

54
@medusajs/icons is built with the following design principles:
55

56
- **Consistency**: All 388 icons follow identical patterns and dimensions (15x15px)
57
- **Type Safety**: Full TypeScript support with IconProps interface
58
- **Accessibility**: Forward-referenced components with proper displayName
59
- **Theme Integration**: Default "currentColor" color for CSS inheritance
60
- **Performance**: Tree-shaking support and optimized SVG output
61
- **Flexibility**: Standard SVG attributes support via props spreading
62
- **Dual Styles**: Outline icons use stroke styling, solid variants use fill styling
63

64
## Capabilities
65

66
### Icon Components
67

68
All 388 icon components are React.forwardRef components that render inline SVG elements with consistent styling and behavior.
69

70
```typescript { .api }
71
/**
72
 * Icon component type - all icons follow this pattern
73
 */
74
type IconComponent = React.ForwardRefExoticComponent<
75
  IconProps & React.RefAttributes<SVGSVGElement>
76
>;
77

78
/**
79
 * Props interface for all icon components
80
 */
81
interface IconProps extends React.SVGAttributes<SVGElement> {
82
  /** Prevents children (icons are self-contained) */
83
  children?: never;
84
  /** Custom color override (defaults to "currentColor") */
85
  color?: string;
86
}
87
```
88

89
### Complete Icon Library
90

91
The library contains 388 icon components organized by functional categories:
92

93
#### Navigation & Actions (47 icons)
94
- **Arrows**: ArrowDown, ArrowLeft, ArrowRight, ArrowUp, ArrowDownCircle, ArrowRightOnRectangle, ArrowUturnLeft, etc.
95
- **Long Arrows**: ArrowLongDown, ArrowLongLeft, ArrowLongRight, ArrowLongUp
96
- **Chevrons**: ChevronDown, ChevronLeft, ChevronRight, ChevronUp, ChevronUpDown, etc.
97
- **Actions**: Check, CheckCircle, CheckCircleSolid, Plus, Minus, X, XCircle, etc.
98

99
#### Interface Elements (35 icons)
100
- **Controls**: Bars variants (BarsThree, BarsArrowDown), Button, Expand, Resize
101
- **Feedback**: Bell variants (BellAlert, BellAlertSolid), ExclamationCircle, InformationCircle
102
- **Progress**: Progress0, Progress15, Progress30, Progress45, Progress60, Progress75, Progress90, Progress100
103
- **Shapes**: Circle variants, Square variants (by color), Triangle variants, Ellipse variants
104

105
#### Content & Communication (28 icons)
106
- **Documents**: Document variants (DocumentText, DocumentSeries), Book, BookOpen, Bookmarks
107
- **Communication**: ChatBubble variants, Envelope, Phone, AtSymbol
108
- **Media**: Photo, Camera, MediaPlay, Pause, PlaySolid, etc.
109

110
#### Business & Commerce (45 icons)
111
- **Shopping**: ShoppingCart, ShoppingBag, Shopping, GiftCards, StoreCredits
112
- **Finance**: Cash, CreditCard, CurrencyDollar, Receipt variants, Tax variants
113
- **Buildings**: Buildings, BuildingStorefront, BuildingTax, House, HouseStar
114

115
#### User & Social (23 icons)
116
- **Users**: User, UserGroup, Users, UsersSolid, UserMini
117
- **Social**: Facebook, Twitter (X), LinkedIn, Discord, Slack, etc.
118
- **Authentication**: Key, Lock variants, Shield variants
119

120
#### Development & Tech (52 icons)
121
- **Code**: Code variants (CodeCommit, CodeMerge, CodePullRequest), CommandLine
122
- **Platforms**: Github, Vercel, NextJs, ReactJs, Typescript, Javascript, etc.
123
- **Tools**: Tools, Puzzle, Component, Server variants, Cloud variants
124

125
#### System & Status (38 icons)
126
- **System**: Cog variants (CogSixTooth), Settings, Computer variants, Server variants
127
- **Status**: Clock variants, History, Loader, Spinner, Fire, Bolt, etc.
128
- **Alerts**: Badge variants, Bell variants, Exclamation variants
129

130
#### Brand & Integration (40 icons)
131
- **Payment**: Stripe, Paypal, Mastercard, Visa, Klarna, etc.
132
- **Shipping**: Shipbob, Shippo, Webshipper, TruckFast, FlyingBox
133
- **Services**: Resend, Sendgrid, Meilisearch, Sanity, Linear, etc.
134

135
#### Utility & Miscellaneous (70 icons)
136
- **Editing**: Pencil variants, Trash, Archive, Clone, etc.
137
- **Navigation**: Map, MapPin, Directions, Levels, etc.
138
- **Objects**: Beaker, Trophy, Gift, Heart, Star, etc.
139
- **Abstract**: Sparkles variants, Wand, Magic effects, etc.
140

141
### Icon Component Examples
142

143
```typescript { .api }
144
// Navigation icons
145
const ArrowRight: IconComponent;
146
const ArrowLeft: IconComponent;
147
const ChevronDown: IconComponent;
148
const Check: IconComponent;
149

150
// User interface icons  
151
const User: IconComponent;
152
const Users: IconComponent;
153
const Cog: IconComponent;
154
const Settings: IconComponent;
155

156
// Business icons
157
const ShoppingCart: IconComponent;
158
const CreditCard: IconComponent;
159
const Buildings: IconComponent;
160

161
// Brand icons
162
const Github: IconComponent;
163
const Stripe: IconComponent;
164
const ReactJs: IconComponent;
165
```
166

167
### Usage Patterns
168

169
**Theme Integration:**
170
```typescript
171
// Icons inherit text color by default
172
<div className="text-blue-500">
173
  <Check /> {/* Will be blue */}
174
</div>
175

176
// Override with custom colors
177
<ArrowRight color="#ef4444" />
178
<User color="var(--primary-color)" />
179
```
180

181
**Event Handling:**
182
```typescript
183
// Icons support all standard SVG event handlers
184
<Trash 
185
  onClick={() => handleDelete()}
186
  onMouseEnter={() => setHovered(true)}
187
  className="cursor-pointer hover:text-red-500"
188
/>
189
```
190

191
**Refs and DOM Access:**
192
```typescript
193
const iconRef = useRef<SVGSVGElement>(null);
194

195
return <Check ref={iconRef} />;
196
```
197

198
**Type Inference (since IconProps is not directly exported):**
199
```typescript
200
// Infer icon prop types from existing components
201
type CheckProps = React.ComponentProps<typeof Check>;
202
type IconRefType = React.ComponentRef<typeof Check>;
203

204
// Use in your own components
205
interface MyComponentProps {
206
  iconProps: CheckProps;
207
}
208
```
209

210
**Accessibility:**
211
```typescript
212
// Add accessibility attributes
213
<User 
214
  role="img"
215
  aria-label="User profile"
216
  tabIndex={0}
217
/>
218
```
219

220
## Types
221

222
```typescript { .api }
223
import * as React from "react";
224

225
/**
226
 * Props interface for all icon components (not directly exported)
227
 * Extends React.SVGAttributes<SVGElement> for full SVG compatibility
228
 * This interface can be inferred from component props: React.ComponentProps<typeof Check>
229
 */
230
interface IconProps extends React.SVGAttributes<SVGElement> {
231
  /** Prevents children - icons are self-contained SVG elements */
232
  children?: never;
233
  /** Custom color override (defaults to "currentColor" for theme integration) */
234
  color?: string;
235
}
236

237
/**
238
 * All icon components follow this type pattern
239
 * Forward-referenced React components rendering SVGSVGElement
240
 */
241
type IconComponent = React.ForwardRefExoticComponent<
242
  IconProps & React.RefAttributes<SVGSVGElement>
243
>;
244
```
245

246
## Error Handling
247

248
Icon components are designed to be robust:
249

250
- **Invalid props**: Unknown props are passed through to the SVG element
251
- **Missing color**: Defaults to "currentColor" which inherits from CSS
252
- **Invalid color values**: Passed directly to SVG stroke/fill attributes
253
- **Ref handling**: Properly forwards refs to the underlying SVG element
254

255
Common error scenarios and their behavior:
256

257
```typescript
258
// These all work as expected
259
<Check color="invalid-color" /> // SVG handles invalid colors gracefully
260
<ArrowRight someCustomProp="value" /> // Passed through to SVG
261
<User ref={null} /> // Handles null refs safely
262
```