0
# Chart Components
1

2
Tremor provides 6 full-featured chart components and 3 compact spark variants, all built on Recharts.
3

4
**All charts share [BaseChartProps](./common-props.md#base-chart-props)** - reference that document for common props like `valueFormatter`, `showLegend`, `onValueChange`, etc.
5

6
## Chart Selection
7

8
| Component | Best For | Unique Props |
9
|-----------|----------|--------------|
10
| AreaChart | Trends, cumulative totals | `stack`, `curveType`, `showGradient`, `connectNulls` |
11
| BarChart | Category comparisons | `layout`, `stack`, `relative`, `barCategoryGap` |
12
| LineChart | Time-series trends | `curveType`, `connectNulls` |
13
| DonutChart | Part-to-whole relationships | `variant: "donut"\|"pie"`, `label`, `showLabel`, `category`, `index` |
14
| ScatterChart | Correlations, distributions | `x`, `y`, `category`, `size`, `sizeRange`, `showOpacity` |
15
| FunnelChart | Conversion funnels | `variant`, `calculateFrom`, `evolutionGradient` |
16
17
## AreaChart
18

19
Filled areas below lines for trends and cumulative values.
20

21
```typescript { .api }
22
interface AreaChartProps extends BaseChartProps {
23
  // Unique props
24
  stack?: boolean;
25
  curveType?: CurveType; // "linear" | "natural" | "monotone" | "step"
26
  connectNulls?: boolean;
27
  showGradient?: boolean;
28
}
29
```
30

31
**Examples:**
32

33
```typescript
34
import { AreaChart } from '@tremor/react';
35

36
// Basic
37
<AreaChart
38
  data={[{ date: '2024-01', revenue: 2890 }, { date: '2024-02', revenue: 2756 }]}
39
  index="date"
40
  categories={['revenue']}
41
  colors={['blue']}
42
  valueFormatter={(v) => `$${v.toLocaleString()}`}
43
/>
44

45
// Stacked with gradient
46
<AreaChart
47
  data={data}
48
  index="date"
49
  categories={['mobile', 'desktop', 'tablet']}
50
  colors={['blue', 'violet', 'cyan']}
51
  stack={true}
52
  showGradient={true}
53
  curveType="monotone"
54
/>
55

56
// Interactive
57
<AreaChart
58
  data={data}
59
  index="date"
60
  categories={['users']}
61
  onValueChange={(e) => console.log(e?.categoryClicked)}
62
/>
63
```
64

65
## BarChart
66

67
Versatile bars for comparisons. Supports vertical/horizontal, stacking, and percentage mode.
68

69
```typescript { .api }
70
interface BarChartProps extends BaseChartProps {
71
  layout?: "vertical" | "horizontal"; // default: "vertical"
72
  stack?: boolean;
73
  relative?: boolean; // 100% stacked percentage mode
74
  barCategoryGap?: string | number;
75
  showAnimation?: boolean;
76
  animationDuration?: number;
77
}
78
```
79

80
**Examples:**
81

82
```typescript
83
import { BarChart } from '@tremor/react';
84

85
// Vertical bars
86
<BarChart
87
  data={[{ product: 'Laptop', sales: 2890 }, { product: 'Phone', sales: 4756 }]}
88
  index="product"
89
  categories={['sales']}
90
  colors={['blue']}
91
/>
92

93
// Horizontal
94
<BarChart data={data} index="product" categories={['sales']} layout="horizontal" />
95

96
// Stacked percentage
97
<BarChart
98
  data={data}
99
  index="month"
100
  categories={['desktop', 'mobile', 'tablet']}
101
  stack={true}
102
  relative={true}
103
  valueFormatter={(v) => `${v}%`}
104
/>
105
```
106

107
## LineChart
108

109
Lines for trend visualization with configurable curves.
110

111
```typescript { .api }
112
interface LineChartProps extends BaseChartProps {
113
  curveType?: CurveType;
114
  connectNulls?: boolean; // Connect lines across null/undefined
115
}
116
```
117

118
**Examples:**
119

120
```typescript
121
import { LineChart } from '@tremor/react';
122

123
// Multi-line with gaps
124
<LineChart
125
  data={[
126
    { month: 'Jan', expected: 2000, actual: 1800 },
127
    { month: 'Feb', expected: 2200, actual: null },
128
    { month: 'Mar', expected: 2400, actual: 2600 }
129
  ]}
130
  index="month"
131
  categories={['expected', 'actual']}
132
  colors={['gray', 'blue']}
133
  curveType="monotone"
134
  connectNulls={false}
135
/>
136

137
// Step line
138
<LineChart data={data} index="date" categories={['value']} curveType="step" />
139
```
140

141
## DonutChart
142

143
Donut/pie charts for categorical proportions with optional center label.
144

145
```typescript { .api }
146
interface DonutChartProps {
147
  data: any[];
148
  category?: string; // Key for values (default: "value")
149
  index?: string; // Key for labels (default: "name")
150
  colors?: (Color | string)[];
151
  variant?: "donut" | "pie";
152
  valueFormatter?: ValueFormatter;
153
  label?: string; // Center label text
154
  showLabel?: boolean;
155
  showAnimation?: boolean;
156
  animationDuration?: number;
157
  showTooltip?: boolean;
158
  noDataText?: string;
159
  onValueChange?: (value: EventProps) => void;
160
  customTooltip?: React.ComponentType<CustomTooltipProps>;
161
}
162
```
163

164
**Examples:**
165

166
```typescript
167
import { DonutChart } from '@tremor/react';
168

169
// Basic donut
170
<DonutChart
171
  data={[
172
    { name: 'Chrome', value: 45 },
173
    { name: 'Safari', value: 30 },
174
    { name: 'Firefox', value: 15 }
175
  ]}
176
  category="value"
177
  index="name"
178
  colors={['blue', 'cyan', 'orange']}
179
  valueFormatter={(v) => `${v}%`}
180
/>
181

182
// With center label
183
<DonutChart data={data} label="Browser Share" showLabel={true} variant="donut" />
184

185
// Pie (no hole)
186
<DonutChart data={data} variant="pie" />
187
```
188

189
## ScatterChart
190

191
Scatter plots for multi-dimensional data visualization with optional bubble sizing.
192

193
```typescript { .api }
194
interface ScatterChartProps extends Omit<BaseChartProps, 'index' | 'categories'> {
195
  data: any[];
196
  x: string; // Key for X-axis values
197
  y: string; // Key for Y-axis values
198
  category: string; // Key for grouping/coloring
199
  size?: string; // Optional key for bubble sizes
200
  valueFormatter?: {
201
    x?: ValueFormatter;
202
    y?: ValueFormatter;
203
    size?: ValueFormatter;
204
  };
205
  sizeRange?: number[]; // [min, max] bubble sizes in px
206
  showOpacity?: boolean;
207
  // Plus all BaseChartProps except index/categories
208
}
209
```
210

211
**Examples:**
212

213
```typescript
214
import { ScatterChart } from '@tremor/react';
215

216
// Basic scatter
217
<ScatterChart
218
  data={[
219
    { product: 'A', price: 29, sales: 2400, category: 'Electronics' },
220
    { product: 'B', price: 42, sales: 3200, category: 'Furniture' }
221
  ]}
222
  x="price"
223
  y="sales"
224
  category="category"
225
  colors={['blue', 'violet']}
226
  xAxisLabel="Price ($)"
227
  yAxisLabel="Sales"
228
  valueFormatter={{ x: (v) => `$${v}`, y: (v) => v.toLocaleString() }}
229
/>
230

231
// Bubble chart (with size)
232
<ScatterChart
233
  data={data}
234
  x="gdp"
235
  y="population"
236
  category="country"
237
  size="co2"
238
  sizeRange={[100, 1000]}
239
  showOpacity={true}
240
/>
241
```
242

243
## FunnelChart
244

245
Conversion funnels for pipelines and multi-step processes.
246

247
```typescript { .api }
248
interface FunnelChartProps {
249
  data: Array<{ value: number; name: string }>;
250
  evolutionGradient?: boolean; // Color gradient based on conversion rates
251
  gradient?: boolean; // Apply color gradient to bars
252
  valueFormatter?: ValueFormatter;
253
  calculateFrom?: "first" | "previous"; // Conversion rate calculation base
254
  color?: Color | string;
255
  variant?: "base" | "center"; // "base" = left-aligned, "center" = centered
256
  yAxisPadding?: number;
257
  showYAxis?: boolean;
258
  showXAxis?: boolean;
259
  showArrow?: boolean;
260
  showGridLines?: boolean;
261
  showTooltip?: boolean;
262
  onValueChange?: (value: EventProps) => void;
263
  customTooltip?: React.ComponentType<CustomTooltipProps>;
264
  noDataText?: string;
265
  rotateLabelX?: { angle: number; verticalShift?: number; xAxisHeight?: number };
266
  barGap?: number | `${number}%`;
267
  xAxisLabel?: string;
268
  yAxisLabel?: string;
269
}
270
```
271

272
**Examples:**
273

274
```typescript
275
import { FunnelChart } from '@tremor/react';
276

277
// Sales funnel
278
<FunnelChart
279
  data={[
280
    { name: 'Visitors', value: 10000 },
281
    { name: 'Sign-ups', value: 2500 },
282
    { name: 'Trial Users', value: 1200 },
283
    { name: 'Paid Users', value: 450 }
284
  ]}
285
  calculateFrom="first"
286
  evolutionGradient={true}
287
  showArrow={true}
288
  valueFormatter={(v) => v.toLocaleString()}
289
/>
290

291
// Centered funnel
292
<FunnelChart data={data} variant="center" color="violet" gradient={true} />
293
```
294

295
## Spark Charts
296

297
Compact inline chart variants optimized for dashboard cards. Share similar props to full-size charts but with minimal chrome (no axes, legends, or tooltips by default).
298

299
```typescript { .api }
300
// Compact line chart
301
interface SparkLineChartProps {
302
  data: any[];
303
  categories: string[];
304
  index: string;
305
  colors?: (Color | string)[];
306
  curveType?: CurveType;
307
  connectNulls?: boolean;
308
  noDataText?: string;
309
  autoMinValue?: boolean;
310
  minValue?: number;
311
  maxValue?: number;
312
}
313

314
// Compact area chart
315
interface SparkAreaChartProps extends SparkLineChartProps {
316
  stack?: boolean;
317
  showGradient?: boolean;
318
  showAnimation?: boolean;
319
  animationDuration?: number;
320
}
321

322
// Compact bar chart
323
interface SparkBarChartProps {
324
  data: any[];
325
  categories: string[];
326
  index: string;
327
  colors?: (Color | string)[];
328
  stack?: boolean;
329
  relative?: boolean;
330
  showAnimation?: boolean;
331
  animationDuration?: number;
332
  noDataText?: string;
333
  autoMinValue?: boolean;
334
  minValue?: number;
335
  maxValue?: number;
336
}
337
```
338

339
**Example:**
340

341
```typescript
342
import { Card, Metric, SparkLineChart } from '@tremor/react';
343

344
<Card>
345
  <Metric>$45,231</Metric>
346
  <SparkLineChart
347
    data={[{ date: '1', value: 120 }, { date: '2', value: 150 }]}
348
    categories={['value']}
349
    index="date"
350
    colors={['emerald']}
351
    className="h-10 mt-2"
352
  />
353
</Card>
354
```
355

356
## Chart Event Handling
357

358
All charts support `onValueChange` for click interactions:
359

360
```typescript
361
const [selected, setSelected] = useState<string | null>(null);
362

363
<BarChart
364
  data={data}
365
  index="month"
366
  categories={['revenue']}
367
  onValueChange={(event) => {
368
    // event is EventProps: { eventType, categoryClicked, ...data }
369
    setSelected(event?.categoryClicked || null);
370
  }}
371
/>
372
```
373

374
## Custom Tooltips
375

376
All charts support custom tooltips via the `customTooltip` prop:
377

378
```typescript
379
const CustomTooltip = ({ payload, active, label }: CustomTooltipProps) => {
380
  if (!active || !payload) return null;
381
  return (
382
    <div className="bg-white p-2 rounded shadow">
383
      <p>{label}</p>
384
      {payload.map((p) => <p key={p.name}>{p.value}</p>)}
385
    </div>
386
  );
387
};
388

389
<BarChart data={data} customTooltip={CustomTooltip} {...props} />
390
```
391

392
## Performance Tips
393

394
- Use `startEndOnly={true}` for large datasets (shows only first/last X-axis labels)
395
- Disable animations by default: `showAnimation={false}` (Tremor default)
396
- For very large datasets (>1000 points), consider data sampling
397
- Use `autoMinValue` to optimize Y-axis scale
398

399
## Common Mistakes
400

401
- ❌ Forgetting required `index` and `categories` props
402
- ❌ Not handling `null` in `onValueChange` callback (check `event?.categoryClicked`)
403
- ❌ Mixing array lengths in data (ensure all objects have same keys)
404
- ❌ Using DonutChart with wrong data shape (needs `value`/`name` or specify `category`/`index`)
405
- ❌ Not providing `valueFormatter` for consistent number display
406

407
## See Also
408

409
- [Common Props Reference](./common-props.md#base-chart-props) for BaseChartProps interface
410
- [Types Reference](./types.md) for EventProps, CustomTooltipProps, CurveType, ValueFormatter
411