0
# List Components
1

2
Advanced list management with Material UI data grids, filtering, sorting, and pagination capabilities for react-admin applications.
3

4
## Capabilities
5

6
### Core List Components
7

8
Primary components for displaying and managing data lists.
9

10
```typescript { .api }
11
/**
12
 * Main list page wrapper component with filtering, sorting, and pagination
13
 * @param props - List configuration props
14
 * @returns Complete list page with data management
15
 */
16
function List(props: ListProps): ReactElement;
17

18
/**
19
 * List actions component for page-level operations
20
 * @param props - ListActions configuration props
21
 * @returns Action buttons for list operations
22
 */
23
function ListActions(props: ListActionsProps): ReactElement;
24

25
/**
26
 * Auto-generated list component based on resource introspection
27
 * @param props - ListGuesser configuration props
28
 * @returns Generated list component
29
 */
30
function ListGuesser(props: ListGuesserProps): ReactElement;
31

32
interface ListProps {
33
  /** Child components (typically Datagrid or SimpleList) */
34
  children?: ReactNode;
35
  /** Custom list actions component */
36
  actions?: ComponentType<ListActionsProps> | false;
37
  /** Custom filters component */
38
  filters?: ReactElement[];
39
  /** Default sort field */
40
  sort?: { field: string; order: 'ASC' | 'DESC' };
41
  /** Records per page */
42
  perPage?: number;
43
  /** Custom pagination component */
44
  pagination?: ComponentType<PaginationProps> | false;
45
  /** Custom bulk actions component */
46
  bulkActionButtons?: ComponentType<BulkActionsProps> | false;
47
  /** Custom empty component */
48
  empty?: ComponentType;
49
}
50

51
interface ListActionsProps {
52
  /** Current filters */
53
  filters?: ReactElement[];
54
  /** Whether to show filter button */
55
  hasCreate?: boolean;
56
  /** Custom create button */
57
  createButton?: ReactElement;
58
  /** Custom export button */
59
  exportButton?: ReactElement;
60
}
61
```
62

63
### Data Grid Components
64

65
Advanced data table components with sorting, selection, and customization.
66

67
```typescript { .api }
68
/**
69
 * Data table component with sorting, selection, and row actions
70
 * @param props - Datagrid configuration props
71
 * @returns Advanced data table with Material UI styling
72
 */
73
function Datagrid(props: DatagridProps): ReactElement;
74

75
/**
76
 * Expandable data grid with collapsible row details
77
 * @param props - ExpandableDatagrid configuration props
78
 * @returns Data grid with expandable rows
79
 */
80
function ExpandableDatagrid(props: ExpandableDatagridProps): ReactElement;
81

82
interface DatagridProps {
83
  /** Child field components */
84
  children?: ReactNode;
85
  /** Row click behavior */
86
  rowClick?: string | Function | false;
87
  /** Custom bulk actions component */
88
  bulkActionButtons?: ReactElement | false;
89
  /** Whether rows are selectable */
90
  isRowSelectable?: (record: any) => boolean;
91
  /** Custom row style function */
92
  rowStyle?: (record: any, index: number) => CSSProperties;
93
  /** Hover effects on rows */
94
  hover?: boolean;
95
  /** Row size variant */
96
  size?: 'small' | 'medium';
97
  /** Custom header component */
98
  header?: ComponentType;
99
  /** Custom body component */
100
  body?: ComponentType;
101
  /** Optimistic updates */
102
  optimized?: boolean;
103
}
104

105
interface ExpandableDatagridProps extends DatagridProps {
106
  /** Expand panel component */
107
  expand?: ComponentType<{ record: any; id: Identifier }>;
108
}
109
```
110

111
### Simple List Components
112

113
Simplified list components for basic data display.
114

115
```typescript { .api }
116
/**
117
 * Simple list component for basic data display
118
 * @param props - SimpleList configuration props
119
 * @returns Simple list layout with Material UI styling
120
 */
121
function SimpleList(props: SimpleListProps): ReactElement;
122

123
/**
124
 * Single field list component for displaying one field per item
125
 * @param props - SingleFieldList configuration props
126
 * @returns List showing single field per record
127
 */
128
function SingleFieldList(props: SingleFieldListProps): ReactElement;
129

130
interface SimpleListProps {
131
  /** Primary text field source */
132
  primaryText?: string | Function;
133
  /** Secondary text field source */
134
  secondaryText?: string | Function;
135
  /** Tertiary text field source */
136
  tertiaryText?: string | Function;
137
  /** Left icon or avatar source */
138
  leftAvatar?: string | Function;
139
  /** Left icon component */
140
  leftIcon?: ComponentType | Function;
141
  /** Right icon component */
142
  rightAvatar?: string | Function;
143
  /** Right icon component */
144
  rightIcon?: ComponentType | Function;
145
  /** Row click behavior */
146
  rowClick?: string | Function;
147
}
148

149
interface SingleFieldListProps {
150
  /** Child field component */
151
  children: ReactElement;
152
  /** Link behavior for items */
153
  linkType?: string | Function | false;
154
}
155
```
156

157
### Filtering Components
158

159
Components for data filtering and search functionality.
160

161
```typescript { .api }
162
/**
163
 * Filter component container for list filtering
164
 * @param props - Filter configuration props
165
 * @returns Filter component with input fields
166
 */
167
function Filter(props: FilterProps): ReactElement;
168

169
/**
170
 * Filter button for toggling filter visibility
171
 * @param props - FilterButton configuration props
172
 * @returns Button for showing/hiding filters
173
 */
174
function FilterButton(props: FilterButtonProps): ReactElement;
175

176
/**
177
 * Search input component for text-based filtering
178
 * @param props - SearchInput configuration props
179
 * @returns Search input with filtering functionality
180
 */
181
function SearchInput(props: SearchInputProps): ReactElement;
182

183
interface FilterProps {
184
  /** Child filter input components */
185
  children?: ReactNode;
186
  /** Default filter values */
187
  defaultValues?: any;
188
  /** Filter form variant */
189
  variant?: 'standard' | 'outlined' | 'filled';
190
}
191

192
interface SearchInputProps {
193
  /** Input placeholder text */
194
  placeholder?: string;
195
  /** Source field to search */
196
  source?: string;
197
  /** Search always on (no submit button) */
198
  alwaysOn?: boolean;
199
  /** Input variant */
200
  variant?: 'standard' | 'outlined' | 'filled';
201
}
202
```
203

204
### Pagination Components
205

206
Components for list pagination and navigation.
207

208
```typescript { .api }
209
/**
210
 * Pagination component with page navigation and sizing
211
 * @param props - Pagination configuration props
212
 * @returns Pagination controls with Material UI styling
213
 */
214
function Pagination(props: PaginationProps): ReactElement;
215

216
/**
217
 * Pagination actions component with next/previous buttons
218
 * @param props - PaginationActions configuration props
219
 * @returns Navigation buttons for pagination
220
 */
221
function PaginationActions(props: PaginationActionsProps): ReactElement;
222

223
/**
224
 * Pagination limit component for controlling page size
225
 * @param props - PaginationLimit configuration props
226
 * @returns Page size selector component
227
 */
228
function PaginationLimit(props: PaginationLimitProps): ReactElement;
229

230
interface PaginationProps {
231
  /** Available page sizes */
232
  rowsPerPageOptions?: number[];
233
  /** Show first/last page buttons */
234
  showFirstButton?: boolean;
235
  /** Show last page button */
236
  showLastButton?: boolean;
237
  /** Pagination actions component */
238
  ActionsComponent?: ComponentType<PaginationActionsProps>;
239
}
240

241
interface PaginationLimitProps {
242
  /** Available page size options */
243
  choices?: number[];
244
  /** Default page size */
245
  defaultValue?: number;
246
}
247
```
248

249
### Bulk Operations
250

251
Components for operations on multiple selected records.
252

253
```typescript { .api }
254
/**
255
 * Bulk actions component for selected records
256
 * @param props - BulkActions configuration props
257
 * @returns Bulk action controls and buttons
258
 */
259
function BulkActions(props: BulkActionsProps): ReactElement;
260

261
/**
262
 * Bulk actions toolbar with selection info and actions
263
 * @param props - BulkActionsToolbar configuration props
264
 * @returns Toolbar with bulk operation controls
265
 */
266
function BulkActionsToolbar(props: BulkActionsToolbarProps): ReactElement;
267

268
interface BulkActionsProps {
269
  /** Child bulk action button components */
270
  children?: ReactNode;
271
  /** Selected record IDs */
272
  selectedIds?: Identifier[];
273
  /** Resource name */
274
  resource?: string;
275
}
276

277
interface BulkActionsToolbarProps {
278
  /** Child bulk action components */
279
  children?: ReactNode;
280
  /** Selected record IDs */
281
  selectedIds?: Identifier[];
282
  /** Selection toggle handler */
283
  onUnselectItems?: () => void;
284
}
285
```
286

287
### Sorting Components
288

289
Components for data sorting functionality.
290

291
```typescript { .api }
292
/**
293
 * Sort button component for column sorting
294
 * @param props - SortButton configuration props
295
 * @returns Sortable column header button
296
 */
297
function SortButton(props: SortButtonProps): ReactElement;
298

299
/**
300
 * Sortable wrapper component for making columns sortable
301
 * @param props - Sortable configuration props
302
 * @returns Sortable column wrapper
303
 */
304
function Sortable(props: SortableProps): ReactElement;
305

306
interface SortButtonProps {
307
  /** Field to sort by */
308
  fields: string[];
309
  /** Button label */
310
  label?: string;
311
  /** Button icon */
312
  icon?: ReactElement;
313
}
314

315
interface SortableProps {
316
  /** Field name for sorting */
317
  field: string;
318
  /** Child component to make sortable */
319
  children: ReactElement;
320
}
321
```
322

323
**Usage Examples:**
324

325
```typescript
326
import { 
327
  List, 
328
  Datagrid, 
329
  TextField, 
330
  NumberField,
331
  DateField,
332
  EditButton,
333
  SearchInput,
334
  Filter,
335
  BulkDeleteButton 
336
} from "ra-ui-materialui";
337

338
// Basic list with datagrid
339
const UserList = () => (
340
  <List>
341
    <Datagrid rowClick="edit">
342
      <TextField source="name" />
343
      <TextField source="email" />
344
      <DateField source="createdAt" />
345
      <EditButton />
346
    </Datagrid>
347
  </List>
348
);
349

350
// List with filters and pagination
351
const ProductList = () => (
352
  <List 
353
    filters={[
354
      <SearchInput source="q" alwaysOn />,
355
      <SelectInput source="category" choices={categories} />
356
    ]}
357
    sort={{ field: 'name', order: 'ASC' }}
358
    perPage={25}
359
  >
360
    <Datagrid 
361
      bulkActionButtons={<BulkDeleteButton />}
362
      rowClick="show"
363
    >
364
      <TextField source="name" />
365
      <NumberField source="price" />
366
      <TextField source="category" />
367
    </Datagrid>
368
  </List>
369
);
370
```
371

372
## Types
373

374
```typescript { .api }
375
type Identifier = string | number;
376

377
interface SortPayload {
378
  field: string;
379
  order: 'ASC' | 'DESC';
380
}
381

382
interface FilterPayload {
383
  [key: string]: any;
384
}
385

386
interface ListControllerResult {
387
  data: any[];
388
  total: number;
389
  loading: boolean;
390
  error?: any;
391
  page: number;
392
  perPage: number;
393
  setPage: (page: number) => void;
394
  setPerPage: (perPage: number) => void;
395
  setSort: (sort: SortPayload) => void;
396
  setFilters: (filters: FilterPayload) => void;
397
  selectedIds: Identifier[];
398
  onSelect: (ids: Identifier[]) => void;
399
  onToggleItem: (id: Identifier) => void;
400
  onUnselectItems: () => void;
401
}
402
```