0
# List Elements
1

2
Semantic HTML list and table components with Tremor styling.
3

4
## Component Overview
5

6
| Component | Purpose |
7
|-----------|---------|
8
| List / ListItem | Vertical lists with dividers, flexbox layout |
9
| Table / TableHead / TableBody / TableFoot | Semantic data tables with sticky headers |
10
| TableRow / TableHeaderCell / TableCell / TableFooterCell | Table structure elements |
11
12
All components are styled wrappers around native HTML elements supporting standard HTML attributes.
13

14
## List & ListItem
15

16
```typescript { .api }
17
interface ListProps extends React.HTMLAttributes<HTMLUListElement> {
18
  children: React.ReactNode; // ListItem components
19
}
20

21
interface ListItemProps extends React.HTMLAttributes<HTMLLIElement> {
22
  children: React.ReactNode; // Uses flexbox with space-between justify
23
}
24
```
25

26
**Examples:**
27

28
```typescript
29
import { List, ListItem } from '@tremor/react';
30

31
// Simple list
32
<List>
33
  <ListItem>Item 1</ListItem>
34
  <ListItem>Item 2</ListItem>
35
  <ListItem>Item 3</ListItem>
36
</List>
37

38
// Key-value pairs (ListItem has justify-between)
39
<List>
40
  <ListItem>
41
    <span>Product Name</span>
42
    <span className="font-medium">$99.99</span>
43
  </ListItem>
44
  <ListItem>
45
    <span>Product Name 2</span>
46
    <span className="font-medium">$149.99</span>
47
  </ListItem>
48
</List>
49

50
// Complex list items
51
<List>
52
  <ListItem>
53
    <div>
54
      <p className="font-medium">Revenue</p>
55
      <p className="text-tremor-content-subtle">Year to date</p>
56
    </div>
57
    <p className="font-semibold">$1,234,567</p>
58
  </ListItem>
59
</List>
60
```
61

62
## Table Components
63

64
Full semantic table structure with responsive overflow scrolling.
65

66
```typescript { .api }
67
// Container with overflow scrolling
68
interface TableProps extends React.TableHTMLAttributes<HTMLTableElement> {
69
  children: React.ReactNode; // TableHead, TableBody, TableFoot
70
}
71

72
// Sections
73
interface TableHeadProps extends React.HTMLAttributes<HTMLTableSectionElement> {
74
  children: React.ReactNode; // TableRow with TableHeaderCell
75
}
76

77
interface TableBodyProps extends React.HTMLAttributes<HTMLTableSectionElement> {
78
  children: React.ReactNode; // TableRow with TableCell
79
}
80

81
interface TableFootProps extends React.HTMLAttributes<HTMLTableSectionElement> {
82
  children: React.ReactNode; // TableRow with TableFooterCell
83
}
84

85
// Rows
86
interface TableRowProps extends React.HTMLAttributes<HTMLTableRowElement> {
87
  children: React.ReactNode;
88
}
89

90
// Cells
91
interface TableHeaderCellProps extends React.ThHTMLAttributes<HTMLTableCellElement> {
92
  children?: React.ReactNode;
93
  scope?: "col" | "row" | "colgroup" | "rowgroup"; // Accessibility
94
}
95

96
interface TableCellProps extends React.TdHTMLAttributes<HTMLTableCellElement> {
97
  children?: React.ReactNode;
98
}
99

100
interface TableFooterCellProps extends React.HTMLAttributes<HTMLTableCellElement> {
101
  children?: React.ReactNode;
102
}
103
```
104

105
**Examples:**
106

107
```typescript
108
import {
109
  Table,
110
  TableHead,
111
  TableBody,
112
  TableFoot,
113
  TableRow,
114
  TableHeaderCell,
115
  TableCell,
116
  TableFooterCell,
117
} from '@tremor/react';
118

119
// Basic table
120
<Table>
121
  <TableHead>
122
    <TableRow>
123
      <TableHeaderCell>Name</TableHeaderCell>
124
      <TableHeaderCell>Status</TableHeaderCell>
125
      <TableHeaderCell>Amount</TableHeaderCell>
126
    </TableRow>
127
  </TableHead>
128
  <TableBody>
129
    <TableRow>
130
      <TableCell>Alice Johnson</TableCell>
131
      <TableCell>Active</TableCell>
132
      <TableCell>$1,234</TableCell>
133
    </TableRow>
134
    <TableRow>
135
      <TableCell>Bob Smith</TableCell>
136
      <TableCell>Inactive</TableCell>
137
      <TableCell>$567</TableCell>
138
    </TableRow>
139
  </TableBody>
140
</Table>
141

142
// With footer totals
143
const data = [
144
  { name: 'Alice', region: 'North', sales: 12500 },
145
  { name: 'Bob', region: 'South', sales: 9800 },
146
];
147
const total = data.reduce((sum, row) => sum + row.sales, 0);
148

149
<Table>
150
  <TableHead>
151
    <TableRow>
152
      <TableHeaderCell scope="col">Name</TableHeaderCell>
153
      <TableHeaderCell scope="col">Region</TableHeaderCell>
154
      <TableHeaderCell scope="col">Sales</TableHeaderCell>
155
    </TableRow>
156
  </TableHead>
157
  <TableBody>
158
    {data.map((row) => (
159
      <TableRow key={row.name}>
160
        <TableCell>{row.name}</TableCell>
161
        <TableCell>{row.region}</TableCell>
162
        <TableCell>${row.sales.toLocaleString()}</TableCell>
163
      </TableRow>
164
    ))}
165
  </TableBody>
166
  <TableFoot>
167
    <TableRow>
168
      <TableFooterCell colSpan={2}>Total</TableFooterCell>
169
      <TableFooterCell>${total.toLocaleString()}</TableFooterCell>
170
    </TableRow>
171
  </TableFoot>
172
</Table>
173

174
// With sticky header (TableHeaderCell has sticky positioning)
175
<div className="max-h-96 overflow-auto">
176
  <Table>
177
    <TableHead>
178
      <TableRow>
179
        <TableHeaderCell>Column 1</TableHeaderCell>
180
        <TableHeaderCell>Column 2</TableHeaderCell>
181
      </TableRow>
182
    </TableHead>
183
    <TableBody>
184
      {/* Many rows... sticky header stays visible */}
185
    </TableBody>
186
  </Table>
187
</div>
188
```
189

190
## Best Practices
191

192
### List Usage
193

194
- Use List/ListItem for simple vertical lists with dividers
195
- ListItem has `justify-between` flexbox - perfect for key-value layouts
196
- Wrap complex content in divs to control layout
197

198
### Table Usage
199

200
- Always use semantic structure: TableHead, TableBody, optionally TableFoot
201
- TableHeaderCell and TableFooterCell render as `<th>` for accessibility
202
- Use `scope` attribute on TableHeaderCell for screen readers
203
- Table automatically handles horizontal overflow with scrolling
204
- TableHeaderCell has sticky positioning (`top-0`) for fixed headers when scrolling
205
- Use `colSpan` and `rowSpan` on cells for complex layouts
206

207
### Accessibility
208

209
```typescript
210
// Good: Proper scope for headers
211
<TableHead>
212
  <TableRow>
213
    <TableHeaderCell scope="col">Name</TableHeaderCell>
214
    <TableHeaderCell scope="col">Value</TableHeaderCell>
215
  </TableRow>
216
</TableHead>
217

218
// Good: Row header
219
<TableBody>
220
  <TableRow>
221
    <TableHeaderCell scope="row">Total</TableHeaderCell>
222
    <TableCell>$1,000</TableCell>
223
  </TableRow>
224
</TableBody>
225
```
226

227
## Design Notes
228

229
- All components support standard HTML attributes for their respective elements
230
- Use React forwardRef for DOM access
231
- Automatically adapt to light/dark mode
232
- No custom Tremor-specific props - they're styled HTML wrappers
233

234
## Common Mistakes
235

236
- ❌ Not using semantic table structure (head/body/foot)
237
- ❌ Using TableCell in TableHead (use TableHeaderCell)
238
- ❌ Forgetting `scope` attribute on headers (accessibility)
239
- ❌ Not wrapping complex ListItem content in divs (layout issues)
240
- ❌ Using List for data tables (use Table instead)
241

242
## See Also
243

244
- [Types Reference](./types.md) for TypeScript types
245