0
# Tremor React
1

2
React component library built on Tailwind CSS with 60+ components for data visualizations, charts, and analytical dashboards.
3

4
**Package**: `@tremor/react` v3.18.7 | **Install**: `npm install @tremor/react`
5
**Peer Deps**: react ^18.0.0, react-dom >=16.6.0
6

7
## Quick Start
8

9
```typescript { .api }
10
import { Card, Title, BarChart } from '@tremor/react';
11

12
const data = [
13
  { name: 'Jan', sales: 2890 },
14
  { name: 'Feb', sales: 2756 },
15
];
16

17
<Card>
18
  <Title>Sales</Title>
19
  <BarChart
20
    data={data}
21
    index="name"
22
    categories={['sales']}
23
    colors={['blue']}
24
    valueFormatter={(v) => `$${v.toLocaleString()}`}
25
  />
26
</Card>
27
```
28

29
## Component Selector
30

31
Use this quick reference to find the right component:
32

33
| Need | Component | Category |
34
|------|-----------|----------|
35
| Display chart data | AreaChart, BarChart, LineChart, DonutChart, ScatterChart, FunnelChart | [Charts](#charts) |
36
| Show rankings/comparisons | BarList | [Visualization](#visualization) |
37
| Display progress | ProgressBar, ProgressCircle | [Visualization](#visualization) |
38
| Show distribution | CategoryBar, DeltaBar, MarkerBar | [Visualization](#visualization) |
39
| Timeline status | Tracker | [Visualization](#visualization) |
40
| Container/card | Card, Dialog | [Layout](#layout) |
41
| Grid/flex layout | Grid, Flex, Col | [Layout](#layout) |
42
| Collapsible sections | Accordion | [Layout](#layout) |
43
| Text input | TextInput, NumberInput, Textarea, SearchSelect | [Input](#input) |
44
| Selection | Select, MultiSelect, DatePicker, DateRangePicker | [Input](#input) |
45
| Actions | Button, Tabs, Switch | [Input](#input) |
46
| Typography | Title, Subtitle, Text, Metric, Callout | [Text](#text) |
47
| Status/labels | Badge, BadgeDelta, Icon | [Icon](#icon) |
48
| Data tables | Table, TableHead, TableBody, List | [List](#list) |
49
| Inline charts | SparkLineChart, SparkAreaChart, SparkBarChart | [Charts](#charts) |
50
51
## Core Imports & Types
52

53
```typescript { .api }
54
// All components export from main package
55
import {
56
  // Charts
57
  AreaChart, BarChart, LineChart, DonutChart, ScatterChart, FunnelChart,
58
  SparkLineChart, SparkAreaChart, SparkBarChart,
59

60
  // Layout
61
  Card, Flex, Grid, Col, Divider, Dialog, DialogPanel, Accordion,
62
  AccordionList, AccordionHeader, AccordionBody,
63

64
  // Visualization
65
  BarList, ProgressBar, ProgressCircle, CategoryBar, DeltaBar, MarkerBar, Tracker,
66

67
  // Input
68
  Button, TextInput, NumberInput, Textarea, Switch,
69
  Select, SelectItem, MultiSelect, MultiSelectItem,
70
  SearchSelect, SearchSelectItem, DatePicker, DateRangePicker, DateRangePickerItem,
71
  TabGroup, TabList, Tab, TabPanels, TabPanel,
72

73
  // Text
74
  Title, Subtitle, Text, Metric, Bold, Italic, Callout, Legend,
75

76
  // Icon
77
  Icon, Badge, BadgeDelta,
78

79
  // List
80
  List, ListItem, Table, TableHead, TableBody, TableFoot, TableRow,
81
  TableHeaderCell, TableCell, TableFooterCell,
82

83
  // Types
84
  type Color, type Size, type ValueFormatter, type CurveType, type DeltaType,
85
  type EventProps, type CustomTooltipProps, type ButtonVariant, type IconVariant,
86

87
  // Utils
88
  getIsBaseColor,
89
} from '@tremor/react';
90

91
// CommonJS also supported
92
const { AreaChart, Card } = require('@tremor/react');
93
```
94

95
**Important Types** - See [common-props.md](./common-props.md) for complete type definitions.
96

97
## Component Categories
98

99
### <a name="charts"></a>Charts
100

101
Full-featured charts built on Recharts. All share [BaseChartProps](./common-props.md#base-chart-props).
102

103
| Component | Use Case | Key Props |
104
|-----------|----------|-----------|
105
| **AreaChart** | Trends, cumulative values | `stack`, `curveType`, `showGradient`, `connectNulls` |
106
| **BarChart** | Comparisons across categories | `layout: "vertical"\|"horizontal"`, `stack`, `relative` |
107
| **LineChart** | Trends over time | `curveType`, `connectNulls` |
108
| **DonutChart** | Categorical proportions | `variant: "donut"\|"pie"`, `label`, `showLabel` |
109
| **ScatterChart** | Multi-dimensional relationships | `x`, `y`, `category`, `size`, `sizeRange` |
110
| **FunnelChart** | Conversion rates, pipelines | `variant: "base"\|"center"`, `calculateFrom`, `evolutionGradient` |
111
112
**Spark Charts** (compact versions): SparkLineChart, SparkAreaChart, SparkBarChart - same props but minimal chrome.
113

114
[Detailed Chart Documentation](./chart-elements.md)
115

116
### <a name="visualization"></a>Visualization
117

118
Specialized data display components.
119

120
| Component | Purpose | Key Props |
121
|-----------|---------|-----------|
122
| **BarList** | Rankings, sorted comparisons | `data`, `sortOrder`, `valueFormatter` |
123
| **ProgressBar** | Linear progress 0-100 | `value`, `color`, `showAnimation` |
124
| **ProgressCircle** | Circular progress | `value`, `size`, `children` (center content) |
125
| **CategoryBar** | 100% stacked distribution | `values`, `colors`, `markerValue` |
126
| **DeltaBar** | +/- change visualization | `value`, `isIncreasePositive` |
127
| **MarkerBar** | Progress with target | `value`, `minValue`, `maxValue` |
128
| **Tracker** | Timeline status blocks | `data: {color, tooltip}[]` |
129
130
[Detailed Visualization Documentation](./visualization-elements.md)
131

132
### <a name="layout"></a>Layout
133

134
Container and structure components.
135

136
| Component | Purpose | Key Props |
137
|-----------|---------|-----------|
138
| **Card** | Content container | `decoration`, `decorationColor` |
139
| **Flex** | Flexbox layout | `flexDirection`, `justifyContent`, `alignItems` |
140
| **Grid** | Responsive grid | `numItems`, `numItemsSm/Md/Lg` |
141
| **Col** | Grid column | `numColSpan`, `numColSpanSm/Md/Lg` |
142
| **Divider** | Visual separator | `children` (optional label) |
143
| **Dialog** | Modal overlay | `open`, `onClose`, `static`, `unmount` |
144
| **Accordion** | Collapsible sections | `defaultOpen` |
145
146
[Detailed Layout Documentation](./layout-elements.md)
147

148
### <a name="input"></a>Input
149

150
Form controls and interactive elements.
151

152
| Component | Purpose | Key Props |
153
|-----------|---------|-----------|
154
| **Button** | Actions | `variant`, `loading`, `icon`, `iconPosition` |
155
| **TextInput** | Single-line text | `value`, `onValueChange`, `error`, `errorMessage` |
156
| **NumberInput** | Numeric input | `enableStepper`, `step`, `min`, `max` |
157
| **Textarea** | Multi-line text | `autoHeight` |
158
| **Switch** | Toggle | `checked`, `onChange` |
159
| **Select** | Dropdown (+ SelectItem) | `enableClear`, requires `<SelectItem>` children |
160
| **MultiSelect** | Multi-select (+ MultiSelectItem) | `placeholderSearch` |
161
| **SearchSelect** | Searchable select (+ SearchSelectItem) | `searchValue`, `onSearchValueChange` |
162
| **DatePicker** | Date selection | `minDate`, `maxDate`, `locale`, `weekStartsOn` |
163
| **DateRangePicker** | Date range (+ DateRangePickerItem) | `enableSelect`, custom presets |
164
| **TabGroup** | Tab navigation | `index`, `onIndexChange`, use with TabList/TabPanels |
165
166
**All inputs support**: `error`, `errorMessage`, `disabled`, `placeholder`
167

168
[Detailed Input Documentation](./input-elements.md)
169

170
### <a name="text"></a>Text
171

172
Typography components.
173

174
| Component | Purpose | Props |
175
|-----------|---------|-------|
176
| **Title** | Main heading | `color` |
177
| **Subtitle** | Secondary heading | `color` |
178
| **Text** | Body text | `color` |
179
| **Metric** | Large numbers/KPIs | `color` |
180
| **Bold / Italic** | Text styling wrappers | - |
181
| **Callout** | Highlighted notice | `title` (required), `icon`, `color` |
182
| **Legend** | Chart legend | `categories`, `colors`, `onClickLegendItem`, `enableLegendSlider` |
183
184
[Detailed Text Documentation](./text-elements.md)
185

186
### <a name="icon"></a>Icon
187

188
Visual indicators and badges.
189

190
| Component | Purpose | Key Props |
191
|-----------|---------|-----------|
192
| **Icon** | Icon wrapper | `icon` (required), `variant`, `size`, `color` |
193
| **Badge** | Status labels | `color`, `size`, `icon` |
194
| **BadgeDelta** | Change indicators | `deltaType`, `isIncreasePositive` |
195
196
[Detailed Icon Documentation](./icon-elements.md)
197

198
### <a name="list"></a>List
199

200
Tables and lists with semantic HTML.
201

202
| Component | Purpose |
203
|-----------|---------|
204
| **List / ListItem** | Vertical lists with dividers |
205
| **Table / TableHead / TableBody / TableFoot** | Data tables |
206
| **TableRow / TableHeaderCell / TableCell / TableFooterCell** | Table structure |
207
208
[Detailed List Documentation](./list-elements.md)
209

210
## Design System
211

212
**Color Palette**: 22 theme colors supporting light/dark modes
213
**Sizing**: `xs | sm | md | lg | xl`
214
**Theme**: Automatic light/dark mode via Tailwind
215

216
[Complete Type Definitions](./types.md) | [Common Props Reference](./common-props.md)
217

218
## Common Patterns
219

220
### Dashboard Layout
221

222
```typescript
223
<div className="p-6 space-y-6">
224
  <Flex justifyContent="between" alignItems="center">
225
    <Title>Dashboard</Title>
226
    <Button>Export</Button>
227
  </Flex>
228

229
  <Grid numItems={1} numItemsSm={2} numItemsLg={4} className="gap-6">
230
    <Card decoration="left" decorationColor="blue">
231
      <Text>Revenue</Text>
232
      <Metric>$45,231</Metric>
233
      <BadgeDelta deltaType="increase">+12%</BadgeDelta>
234
    </Card>
235
    {/* More cards... */}
236
  </Grid>
237
</div>
238
```
239

240
### Form with Validation
241

242
```typescript
243
const [value, setValue] = useState('');
244
const [error, setError] = useState('');
245

246
<TextInput
247
  value={value}
248
  onValueChange={(v) => {
249
    setValue(v);
250
    setError(v ? '' : 'Required');
251
  }}
252
  error={!!error}
253
  errorMessage={error}
254
/>
255
```
256

257
### Interactive Chart
258

259
```typescript
260
const [selected, setSelected] = useState<string | null>(null);
261

262
<BarChart
263
  data={data}
264
  index="date"
265
  categories={['revenue']}
266
  onValueChange={(v) => setSelected(v?.categoryClicked || null)}
267
/>
268
```
269

270
## Best Practices
271

272
1. **Always use valueFormatter** for consistent number formatting
273
2. **Use Tremor palette colors** for light/dark mode consistency
274
3. **Provide meaningful ARIA labels** for accessibility
275
4. **Use startEndOnly** for large datasets to reduce axis labels
276
5. **Controlled vs uncontrolled**: Use `value/onChange` (controlled) or `defaultValue` (uncontrolled)
277

278
## Common Mistakes
279

280
- ❌ Forgetting `SelectItem` children for `Select` component
281
- ❌ Not handling `null` in chart `onValueChange`
282
- ❌ Using non-Tremor colors without testing dark mode
283
- ❌ Forgetting `index` prop on charts (required)
284
- ❌ Not providing `enableClear` for Select when clearing is needed
285

286
## Type Safety
287

288
```typescript
289
import { type Color, type Size, type ValueFormatter } from '@tremor/react';
290

291
// Type-safe props
292
const chartColor: Color = 'blue'; // ✓
293
const customFormatter: ValueFormatter = (v) => `$${v}`; // ✓
294
```
295

296
## Performance Tips
297

298
- Use `startEndOnly` for charts with many data points
299
- Enable `showAnimation: false` (default) for better performance
300
- Implement virtualization for large tables (use external library)
301
- Use `React.memo` for metric cards that don't change frequently
302