0
# Icon Components
1

2
Icon wrapper and badge components for visual indicators, status labels, and markers.
3

4
## Icon Component Selection
5

6
| Component | Use Case | Key Props |
7
|-----------|----------|-----------|
8
| Icon | Styled icon wrapper | `icon` (required), `variant`, `size`, `color` |
9
| Badge | Status labels, tags | `color`, `size`, `icon` |
10
| BadgeDelta | Change indicators | `deltaType`, `isIncreasePositive`, `size` |
11
12
## Icon
13

14
Flexible icon wrapper with multiple styling variants.
15

16
```typescript { .api }
17
interface IconProps extends React.HTMLAttributes<HTMLSpanElement> {
18
  icon: React.ElementType; // Required
19
  variant?: "simple" | "light" | "shadow" | "solid" | "outlined";
20
  tooltip?: string;
21
  size?: Size; // "xs" | "sm" | "md" | "lg" | "xl"
22
  color?: Color;
23
}
24
```
25

26
**Examples:**
27

28
```typescript
29
import { Icon } from '@tremor/react';
30
import { UserIcon, BellIcon } from '@heroicons/react/24/outline';
31

32
// Basic
33
<Icon icon={UserIcon} />
34

35
// Variants
36
<Icon icon={BellIcon} variant="simple" />
37
<Icon icon={BellIcon} variant="light" />
38
<Icon icon={BellIcon} variant="solid" />
39
<Icon icon={BellIcon} variant="outlined" />
40

41
// Colored
42
<Icon icon={UserIcon} color="blue" />
43
<Icon icon={UserIcon} color="emerald" variant="solid" />
44

45
// Sizes
46
<Icon icon={UserIcon} size="xs" />
47
<Icon icon={UserIcon} size="lg" />
48

49
// With tooltip
50
<Icon icon={BellIcon} tooltip="Notifications" variant="solid" color="blue" />
51

52
// In layouts
53
<Flex alignItems="center" className="gap-2">
54
  <Icon icon={UserIcon} color="gray" />
55
  <Text>John Doe</Text>
56
</Flex>
57
```
58

59
## Badge
60

61
Labels and status indicators with optional icons.
62

63
```typescript { .api }
64
interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
65
  color?: Color;
66
  size?: Size;
67
  icon?: React.ElementType;
68
  tooltip?: string;
69
  children?: React.ReactNode;
70
}
71
```
72

73
**Examples:**
74

75
```typescript
76
import { Badge, Card, Title, Flex } from '@tremor/react';
77
import { CheckCircleIcon, ClockIcon, XCircleIcon } from '@heroicons/react/24/outline';
78

79
// Basic
80
<Badge>New</Badge>
81

82
// Status badges
83
<Badge color="emerald">Active</Badge>
84
<Badge color="amber">Pending</Badge>
85
<Badge color="red">Inactive</Badge>
86
<Badge color="blue">In Progress</Badge>
87

88
// With icons
89
<Badge icon={CheckCircleIcon} color="emerald">Completed</Badge>
90
<Badge icon={ClockIcon} color="amber">Pending</Badge>
91
<Badge icon={XCircleIcon} color="red">Failed</Badge>
92

93
// Sizes
94
<Badge size="xs">Tiny</Badge>
95
<Badge size="lg">Large</Badge>
96

97
// In cards
98
<Card>
99
  <Flex justifyContent="between" alignItems="center">
100
    <Title>Project Status</Title>
101
    <Badge icon={CheckCircleIcon} color="emerald">On Track</Badge>
102
  </Flex>
103
</Card>
104

105
// Multiple badges (tags)
106
<Flex className="gap-2">
107
  <Badge color="blue">React</Badge>
108
  <Badge color="violet">TypeScript</Badge>
109
  <Badge color="emerald">Tailwind</Badge>
110
</Flex>
111
```
112

113
## BadgeDelta
114

115
Specialized badge for displaying directional change indicators.
116

117
```typescript { .api }
118
interface BadgeDeltaProps extends React.HTMLAttributes<HTMLSpanElement> {
119
  deltaType?: "increase" | "moderateIncrease" | "decrease" | "moderateDecrease" | "unchanged";
120
  isIncreasePositive?: boolean; // default: true
121
  size?: Size;
122
  tooltip?: string;
123
  children?: React.ReactNode; // Delta value text (e.g., "+12%")
124
}
125
```
126

127
**Examples:**
128

129
```typescript
130
import { BadgeDelta, Card, Metric, Text, Flex } from '@tremor/react';
131

132
// Delta types
133
<BadgeDelta deltaType="increase">+23.5%</BadgeDelta>
134
<BadgeDelta deltaType="moderateIncrease">+5.2%</BadgeDelta>
135
<BadgeDelta deltaType="unchanged">0%</BadgeDelta>
136
<BadgeDelta deltaType="moderateDecrease">-2.1%</BadgeDelta>
137
<BadgeDelta deltaType="decrease">-15.8%</BadgeDelta>
138

139
// Negative is positive (e.g., cost reduction)
140
<BadgeDelta deltaType="decrease" isIncreasePositive={false}>-12% costs</BadgeDelta>
141

142
// Metric card with delta
143
<Card>
144
  <Flex justifyContent="between" alignItems="start">
145
    <div>
146
      <Text>Total Revenue</Text>
147
      <Metric>$45,231</Metric>
148
    </div>
149
    <BadgeDelta deltaType="increase">+12.3%</BadgeDelta>
150
  </Flex>
151
  <Text className="mt-4" color="gray">Compared to last month</Text>
152
</Card>
153

154
// Sizes
155
<BadgeDelta deltaType="increase" size="xs">+5%</BadgeDelta>
156
<BadgeDelta deltaType="increase" size="lg">+5%</BadgeDelta>
157

158
// With tooltip
159
<BadgeDelta
160
  deltaType="increase"
161
  tooltip="Increased by $5,420 from last month"
162
>
163
  +12.3%
164
</BadgeDelta>
165
```
166

167
## Delta Type Helper
168

169
```typescript
170
import type { DeltaType } from '@tremor/react';
171

172
function getDeltaType(changePercent: number): DeltaType {
173
  if (changePercent === 0) return 'unchanged';
174
  if (changePercent > 0) {
175
    return changePercent >= 10 ? 'increase' : 'moderateIncrease';
176
  }
177
  return changePercent <= -10 ? 'decrease' : 'moderateDecrease';
178
}
179

180
// Usage
181
const change = 15.5;
182
<BadgeDelta deltaType={getDeltaType(change)}>
183
  {change > 0 ? '+' : ''}{change}%
184
</BadgeDelta>
185
```
186

187
## Color Semantics
188

189
Consistent color meanings:
190

191
```typescript
192
// Status
193
<Badge color="emerald">Success/Active/Completed</Badge>
194
<Badge color="blue">Info/In Progress/Default</Badge>
195
<Badge color="amber">Warning/Pending/Review</Badge>
196
<Badge color="red">Error/Failed/Inactive</Badge>
197
<Badge color="gray">Neutral/Disabled/Draft</Badge>
198

199
// Priority
200
<Badge color="red">High Priority</Badge>
201
<Badge color="amber">Medium Priority</Badge>
202
<Badge color="blue">Low Priority</Badge>
203
```
204

205
## Icon Sources
206

207
Works with any icon library:
208

209
```typescript
210
// Heroicons (recommended)
211
import { UserIcon } from '@heroicons/react/24/outline';
212
<Icon icon={UserIcon} />
213

214
// Lucide React
215
import { User } from 'lucide-react';
216
<Icon icon={User} />
217

218
// Custom SVG
219
function CustomIcon(props: React.SVGProps<SVGSVGElement>) {
220
  return <svg {...props} viewBox="0 0 24 24"><path d="..." /></svg>;
221
}
222
<Icon icon={CustomIcon} />
223
```
224

225
## Accessibility
226

227
```typescript
228
// Decorative icons
229
<Icon icon={UserIcon} aria-hidden="true" />
230

231
// Semantic icons
232
<Icon
233
  icon={BellIcon}
234
  tooltip="3 new notifications"
235
  role="img"
236
  aria-label="3 new notifications"
237
/>
238

239
// Badges with screen reader text
240
<Badge color="emerald">
241
  <span className="sr-only">Status: </span>
242
  Active
243
</Badge>
244
```
245

246
## Common Mistakes
247

248
- ❌ Forgetting `icon` prop for Icon component (required!)
249
- ❌ Using wrong deltaType (use helper function for automatic selection)
250
- ❌ Inconsistent color usage for status badges
251
- ❌ Not providing tooltip for icons with semantic meaning
252
- ❌ Using Badge for change indicators (use BadgeDelta instead)
253

254
## See Also
255

256
- [Types Reference](./types.md) for Color, Size, DeltaType, IconVariant types and delta helper function
257