0
# List Views & Data Display
1

2
React Admin provides powerful components for displaying and interacting with collections of data. The list system supports pagination, sorting, filtering, bulk actions, and various display formats from simple lists to complex data grids.
3

4
## List Component
5

6
The `<List>` component is the main container for list views, handling data fetching, pagination, sorting, and filtering.
7

8
```typescript { .api }
9
import { List } from 'react-admin';
10

11
interface ListProps {
12
  title?: string | React.ReactElement;
13
  actions?: React.ReactElement | false;
14
  filters?: React.ReactElement;
15
  pagination?: React.ReactElement | false;
16
  perPage?: number;
17
  sort?: { field: string; order: 'ASC' | 'DESC' };
18
  filter?: any;
19
  filterDefaultValues?: any;
20
  disableSyncWithLocation?: boolean;
21
  exporter?: Exporter | false;
22
  bulkActionButtons?: React.ReactElement | false;
23
  empty?: React.ReactElement;
24
  emptyWhileLoading?: boolean;
25
  children: React.ReactNode;
26
  className?: string;
27
  sx?: any;
28
  resource?: string;
29
  hasCreate?: boolean;
30
  hasEdit?: boolean;
31
  hasShow?: boolean;
32
  aside?: React.ReactElement;
33
  component?: React.ElementType;
34
  queryOptions?: UseQueryOptions;
35
  debounce?: number;
36
  storeKey?: string | false;
37
}
38

39
const List: React.FC<ListProps>;
40
```
41

42
### Basic List Usage
43

44
```typescript
45
import { List, Datagrid, TextField, DateField, EditButton } from 'react-admin';
46

47
const PostList = () => (
48
  <List>
49
    <Datagrid>
50
      <TextField source="id" />
51
      <TextField source="title" />
52
      <DateField source="published_at" />
53
      <EditButton />
54
    </Datagrid>
55
  </List>
56
);
57
```
58

59
### List with Custom Features
60

61
```typescript
62
import { 
63
  List, 
64
  Datagrid, 
65
  TextField, 
66
  DateField, 
67
  BulkDeleteButton,
68
  CreateButton,
69
  ExportButton,
70
  TopToolbar
71
} from 'react-admin';
72

73
const PostList = () => {
74
  const PostListActions = () => (
75
    <TopToolbar>
76
      <CreateButton />
77
      <ExportButton />
78
    </TopToolbar>
79
  );
80

81
  const PostBulkActions = () => (
82
    <>
83
      <BulkDeleteButton />
84
    </>
85
  );
86

87
  return (
88
    <List
89
      title="Blog Posts"
90
      actions={<PostListActions />}
91
      bulkActionButtons={<PostBulkActions />}
92
      sort={{ field: 'published_at', order: 'DESC' }}
93
      perPage={25}
94
      filters={<PostFilter />}
95
    >
96
      <Datagrid>
97
        <TextField source="title" />
98
        <TextField source="author" />
99
        <DateField source="published_at" />
100
        <EditButton />
101
      </Datagrid>
102
    </List>
103
  );
104
};
105
```
106

107
## Datagrid Component
108

109
The `<Datagrid>` component displays data in a table format with sorting, selection, and row actions.
110

111
```typescript { .api }
112
import { Datagrid } from 'react-admin';
113

114
interface DatagridProps {
115
  body?: React.ComponentType<DatagridBodyProps>;
116
  row?: React.ComponentType<DatagridRowProps>;
117
  rowStyle?: Function;
118
  rowSx?: Function;
119
  rowClick?: string | Function | false;
120
  isRowSelectable?: Function;
121
  isRowExpandable?: Function;
122
  expand?: React.ReactElement;
123
  expandSingle?: boolean;
124
  bulkActionButtons?: React.ReactElement | false;
125
  hover?: boolean;
126
  size?: 'small' | 'medium';
127
  empty?: React.ReactElement;
128
  optimized?: boolean;
129
  children: React.ReactNode;
130
  className?: string;
131
  sx?: any;
132
}
133

134
const Datagrid: React.FC<DatagridProps>;
135
```
136

137
### Datagrid Features
138

139
```typescript
140
import { Datagrid, TextField, BooleanField, DateField, ShowButton, EditButton } from 'react-admin';
141

142
const ProductDatagrid = () => (
143
  <Datagrid
144
    rowClick="edit"
145
    bulkActionButtons={<BulkActionsToolbar />}
146
    expand={<ProductDetail />}
147
    isRowSelectable={record => record.published}
148
    rowSx={record => ({ 
149
      backgroundColor: record.featured ? '#ffe' : 'inherit' 
150
    })}
151
  >
152
    <TextField source="name" />
153
    <TextField source="category" />
154
    <BooleanField source="published" />
155
    <DateField source="created_at" />
156
    <ShowButton />
157
    <EditButton />
158
  </Datagrid>
159
);
160
```
161

162
## Field Components
163

164
Field components display individual data values within lists and detail views.
165

166
### TextField
167

168
Display text and string values.
169

170
```typescript { .api }
171
import { TextField } from 'react-admin';
172

173
interface FieldProps {
174
  source: string;
175
  label?: string | false;
176
  sortable?: boolean;
177
  sortBy?: string;
178
  className?: string;
179
  cellClassName?: string;
180
  headerClassName?: string;
181
  textAlign?: 'left' | 'right' | 'center';
182
  emptyText?: string;
183
  sx?: any;
184
  sortByOrder?: 'ASC' | 'DESC';
185
}
186

187
const TextField: React.FC<FieldProps>;
188
```
189

190
### NumberField
191

192
Display numeric values with formatting.
193

194
```typescript { .api }
195
import { NumberField } from 'react-admin';
196

197
interface NumberFieldProps extends FieldProps {
198
  locales?: string | string[];
199
  options?: Intl.NumberFormatOptions;
200
}
201

202
const NumberField: React.FC<NumberFieldProps>;
203
```
204

205
#### Usage Examples
206

207
```typescript
208
// Basic number field
209
<NumberField source="price" />
210

211
// Currency formatting
212
<NumberField 
213
  source="price" 
214
  options={{ 
215
    style: 'currency', 
216
    currency: 'USD' 
217
  }}
218
/>
219

220
// Percentage formatting
221
<NumberField 
222
  source="discount" 
223
  options={{ 
224
    style: 'percent',
225
    minimumFractionDigits: 2
226
  }}
227
/>
228
```
229

230
### DateField
231

232
Display dates with localization and formatting.
233

234
```typescript { .api }
235
import { DateField } from 'react-admin';
236

237
interface DateFieldProps extends FieldProps {
238
  showTime?: boolean;
239
  locales?: string | string[];
240
  options?: Intl.DateTimeFormatOptions;
241
  transform?: (value: any) => Date;
242
}
243

244
const DateField: React.FC<DateFieldProps>;
245
```
246

247
#### Usage Examples
248

249
```typescript
250
// Date only
251
<DateField source="created_at" />
252

253
// Date and time
254
<DateField source="updated_at" showTime />
255

256
// Custom format
257
<DateField 
258
  source="published_at" 
259
  options={{ 
260
    weekday: 'long', 
261
    year: 'numeric', 
262
    month: 'long', 
263
    day: 'numeric' 
264
  }}
265
/>
266
```
267

268
### BooleanField
269

270
Display boolean values as icons or text.
271

272
```typescript { .api }
273
import { BooleanField } from 'react-admin';
274

275
interface BooleanFieldProps extends FieldProps {
276
  valueLabelTrue?: string;
277
  valueLabelFalse?: string;
278
  TrueIcon?: React.ComponentType;
279
  FalseIcon?: React.ComponentType;
280
}
281

282
const BooleanField: React.FC<BooleanFieldProps>;
283
```
284

285
### EmailField
286

287
Display email addresses as clickable mailto links.
288

289
```typescript { .api }
290
import { EmailField } from 'react-admin';
291

292
const EmailField: React.FC<FieldProps>;
293
```
294

295
### UrlField
296

297
Display URLs as clickable links.
298

299
```typescript { .api }
300
import { UrlField } from 'react-admin';
301

302
const UrlField: React.FC<FieldProps>;
303
```
304

305
### ImageField
306

307
Display images from URLs.
308

309
```typescript { .api }
310
import { ImageField } from 'react-admin';
311

312
interface ImageFieldProps extends FieldProps {
313
  src?: string;
314
  title?: string;
315
  alt?: string;
316
}
317

318
const ImageField: React.FC<ImageFieldProps>;
319
```
320

321
### FileField
322

323
Display files as download links.
324

325
```typescript { .api }
326
import { FileField } from 'react-admin';
327

328
interface FileFieldProps extends FieldProps {
329
  src?: string;
330
  title?: string;
331
  target?: string;
332
}
333

334
const FileField: React.FC<FileFieldProps>;
335
```
336

337
### ChipField
338

339
Display values as Material-UI chips.
340

341
```typescript { .api }
342
import { ChipField } from 'react-admin';
343

344
interface ChipFieldProps extends FieldProps {
345
  size?: 'small' | 'medium';
346
  variant?: 'filled' | 'outlined';
347
  color?: 'default' | 'primary' | 'secondary';
348
  clickable?: boolean;
349
  onClick?: Function;
350
}
351

352
const ChipField: React.FC<ChipFieldProps>;
353
```
354

355
### SelectField
356

357
Display choice values with labels.
358

359
```typescript { .api }
360
import { SelectField } from 'react-admin';
361

362
interface SelectFieldProps extends FieldProps {
363
  choices: ChoiceType[];
364
  optionText?: string | Function;
365
  optionValue?: string;
366
  translateChoice?: boolean;
367
}
368

369
const SelectField: React.FC<SelectFieldProps>;
370
```
371

372
### ArrayField
373

374
Display array values in various formats.
375

376
```typescript { .api }
377
import { ArrayField } from 'react-admin';
378

379
interface ArrayFieldProps extends FieldProps {
380
  children?: React.ReactElement;
381
}
382

383
const ArrayField: React.FC<ArrayFieldProps>;
384
```
385

386
#### Usage Example
387

388
```typescript
389
<ArrayField source="tags">
390
  <SingleFieldList>
391
    <ChipField source="name" />
392
  </SingleFieldList>
393
</ArrayField>
394
```
395

396
### FunctionField
397

398
Display computed values using a custom function.
399

400
```typescript { .api }
401
import { FunctionField } from 'react-admin';
402

403
interface FunctionFieldProps extends Omit<FieldProps, 'source'> {
404
  render: (record: RaRecord, source?: string) => any;
405
  source?: string;
406
}
407

408
const FunctionField: React.FC<FunctionFieldProps>;
409
```
410

411
#### Usage Example
412

413
```typescript
414
<FunctionField 
415
  label="Full Name"
416
  render={record => `${record.firstName} ${record.lastName}`}
417
/>
418

419
<FunctionField
420
  label="Total"
421
  render={record => record.quantity * record.price}
422
/>
423
```
424

425
## Reference Fields
426

427
### ReferenceField
428

429
Display values from referenced records.
430

431
```typescript { .api }
432
import { ReferenceField } from 'react-admin';
433

434
interface ReferenceFieldProps extends FieldProps {
435
  reference: string;
436
  children: React.ReactElement;
437
  link?: string | Function | false;
438
  queryOptions?: UseQueryOptions;
439
}
440

441
const ReferenceField: React.FC<ReferenceFieldProps>;
442
```
443

444
#### Usage Example
445

446
```typescript
447
<ReferenceField source="categoryId" reference="categories" link="show">
448
  <TextField source="name" />
449
</ReferenceField>
450

451
<ReferenceField source="authorId" reference="users" link={false}>
452
  <FunctionField render={record => `${record.firstName} ${record.lastName}`} />
453
</ReferenceField>
454
```
455

456
### ReferenceArrayField
457

458
Display multiple referenced records.
459

460
```typescript { .api }
461
import { ReferenceArrayField } from 'react-admin';
462

463
interface ReferenceArrayFieldProps extends FieldProps {
464
  reference: string;
465
  children: React.ReactElement;
466
  sort?: { field: string; order: 'ASC' | 'DESC' };
467
  filter?: any;
468
  perPage?: number;
469
}
470

471
const ReferenceArrayField: React.FC<ReferenceArrayFieldProps>;
472
```
473

474
#### Usage Example
475

476
```typescript
477
<ReferenceArrayField source="tagIds" reference="tags">
478
  <SingleFieldList>
479
    <ChipField source="name" />
480
  </SingleFieldList>
481
</ReferenceArrayField>
482
```
483

484
### ReferenceManyField
485

486
Display records that reference the current record.
487

488
```typescript { .api }
489
import { ReferenceManyField } from 'react-admin';
490

491
interface ReferenceManyFieldProps extends FieldProps {
492
  reference: string;
493
  target: string;
494
  children: React.ReactElement;
495
  sort?: { field: string; order: 'ASC' | 'DESC' };
496
  filter?: any;
497
  perPage?: number;
498
  pagination?: React.ReactElement;
499
}
500

501
const ReferenceManyField: React.FC<ReferenceManyFieldProps>;
502
```
503

504
#### Usage Example
505

506
```typescript
507
<ReferenceManyField 
508
  label="Comments" 
509
  reference="comments" 
510
  target="postId"
511
  sort={{ field: 'created_at', order: 'DESC' }}
512
>
513
  <Datagrid>
514
    <TextField source="author" />
515
    <TextField source="body" />
516
    <DateField source="created_at" />
517
  </Datagrid>
518
</ReferenceManyField>
519
```
520

521
## Alternative List Layouts
522

523
### SimpleList
524

525
Simple list layout for mobile-friendly displays.
526

527
```typescript { .api }
528
import { SimpleList } from 'react-admin';
529

530
interface SimpleListProps {
531
  primaryText?: string | Function;
532
  secondaryText?: string | Function;
533
  tertiaryText?: string | Function;
534
  leftAvatar?: string | Function | React.ReactElement;
535
  leftIcon?: string | Function | React.ReactElement;
536
  rightAvatar?: string | Function | React.ReactElement;
537
  rightIcon?: string | Function | React.ReactElement;
538
  linkType?: string | Function | false;
539
  rowStyle?: Function;
540
  rowSx?: Function;
541
  className?: string;
542
  sx?: any;
543
}
544

545
const SimpleList: React.FC<SimpleListProps>;
546
```
547

548
#### Usage Example
549

550
```typescript
551
<List>
552
  <SimpleList
553
    primaryText={record => record.title}
554
    secondaryText={record => `${record.views} views`}
555
    tertiaryText={record => new Date(record.published_at).toLocaleDateString()}
556
    linkType="show"
557
  />
558
</List>
559
```
560

561
### SingleFieldList
562

563
Display a single field for each record.
564

565
```typescript { .api }
566
import { SingleFieldList } from 'react-admin';
567

568
interface SingleFieldListProps {
569
  linkType?: string | Function | false;
570
  children: React.ReactElement;
571
  className?: string;
572
  sx?: any;
573
}
574

575
const SingleFieldList: React.FC<SingleFieldListProps>;
576
```
577

578
### InfiniteList
579

580
List with infinite scrolling.
581

582
```typescript { .api }
583
import { InfiniteList } from 'react-admin';
584

585
const InfiniteList: React.FC<ListProps>;
586
```
587

588
## Filtering
589

590
### Filter Components
591

592
```typescript { .api }
593
import { Filter, SearchInput, SelectInput, DateInput } from 'react-admin';
594

595
const PostFilter = () => (
596
  <Filter>
597
    <SearchInput source="q" alwaysOn />
598
    <SelectInput 
599
      source="status" 
600
      choices={[
601
        { id: 'published', name: 'Published' },
602
        { id: 'draft', name: 'Draft' }
603
      ]} 
604
    />
605
    <DateInput source="published_since" />
606
  </Filter>
607
);
608
```
609

610
### Advanced Filtering
611

612
```typescript
613
import { List, Datagrid, Filter, TextInput, ReferenceInput, SelectInput } from 'react-admin';
614

615
const PostFilter = () => (
616
  <Filter>
617
    <TextInput label="Search" source="q" alwaysOn />
618
    <ReferenceInput source="categoryId" reference="categories" allowEmpty>
619
      <SelectInput optionText="name" />
620
    </ReferenceInput>
621
    <SelectInput
622
      source="status"
623
      choices={[
624
        { id: 'published', name: 'Published' },
625
        { id: 'draft', name: 'Draft' },
626
        { id: 'rejected', name: 'Rejected' }
627
      ]}
628
    />
629
  </Filter>
630
);
631

632
const PostList = () => (
633
  <List filters={<PostFilter />}>
634
    <Datagrid>
635
      <TextField source="title" />
636
      <TextField source="status" />
637
      <DateField source="published_at" />
638
    </Datagrid>
639
  </List>
640
);
641
```
642

643
## Pagination
644

645
### Pagination Component
646

647
```typescript { .api }
648
import { Pagination } from 'react-admin';
649

650
interface PaginationProps {
651
  rowsPerPageOptions?: number[];
652
  showFirstButton?: boolean;
653
  showLastButton?: boolean;
654
  className?: string;
655
  sx?: any;
656
}
657

658
const Pagination: React.FC<PaginationProps>;
659
```
660

661
### Custom Pagination
662

663
```typescript
664
<List pagination={<Pagination rowsPerPageOptions={[10, 25, 50, 100]} />}>
665
  <Datagrid>
666
    <TextField source="title" />
667
  </Datagrid>
668
</List>
669
```
670

671
## Bulk Actions
672

673
### Built-in Bulk Actions
674

675
```typescript { .api }
676
import { 
677
  BulkDeleteButton, 
678
  BulkUpdateButton,
679
  BulkExportButton 
680
} from 'react-admin';
681

682
const BulkActionsToolbar = () => (
683
  <>
684
    <BulkDeleteButton />
685
    <BulkUpdateButton 
686
      data={{ published: true }} 
687
      label="Publish Selected"
688
    />
689
    <BulkExportButton />
690
  </>
691
);
692
```
693

694
### Custom Bulk Actions
695

696
```typescript
697
import { Button, useListContext, useUnselectAll } from 'react-admin';
698

699
const BulkArchiveButton = () => {
700
  const { selectedIds } = useListContext();
701
  const unselectAll = useUnselectAll('posts');
702
  
703
  const handleArchive = () => {
704
    // Archive selected records
705
    console.log('Archiving:', selectedIds);
706
    unselectAll();
707
  };
708
  
709
  return (
710
    <Button
711
      label="Archive"
712
      onClick={handleArchive}
713
      disabled={selectedIds.length === 0}
714
    />
715
  );
716
};
717
```
718

719
## List Context and Hooks
720

721
### useListContext
722

723
Access list state and methods.
724

725
```typescript { .api }
726
import { useListContext } from 'react-admin';
727

728
const useListContext: () => {
729
  data: RaRecord[];
730
  isLoading: boolean;
731
  error: any;
732
  total: number;
733
  page: number;
734
  perPage: number;
735
  setPage: (page: number) => void;
736
  setPerPage: (perPage: number) => void;
737
  setSort: (sort: { field: string; order: 'ASC' | 'DESC' }) => void;
738
  setFilters: (filters: any, displayedFilters?: any) => void;
739
  showFilter: (filterName: string, defaultValue?: any) => void;
740
  hideFilter: (filterName: string) => void;
741
  filterValues: any;
742
  displayedFilters: any;
743
  selectedIds: Identifier[];
744
  onSelect: (ids: Identifier[]) => void;
745
  onToggleItem: (id: Identifier) => void;
746
  onUnselectItems: () => void;
747
  sort: { field: string; order: 'ASC' | 'DESC' };
748
  resource: string;
749
  refetch: () => void;
750
};
751
```
752

753
## Empty States
754

755
### Custom Empty State
756

757
```typescript
758
import { List, Empty } from 'react-admin';
759

760
const CustomEmpty = () => (
761
  <Empty>
762
    <h2>No posts yet</h2>
763
    <p>Create your first post to get started</p>
764
    <CreateButton />
765
  </Empty>
766
);
767

768
const PostList = () => (
769
  <List empty={<CustomEmpty />}>
770
    <Datagrid>
771
      <TextField source="title" />
772
    </Datagrid>
773
  </List>
774
);
775
```
776

777
## Advanced Examples
778

779
### Expandable Rows
780

781
```typescript
782
import { List, Datagrid, TextField, useRecordContext } from 'react-admin';
783

784
const PostPanel = () => {
785
  const record = useRecordContext();
786
  return (
787
    <div style={{ padding: 16 }}>
788
      <strong>Description:</strong> {record.description}
789
    </div>
790
  );
791
};
792

793
const PostList = () => (
794
  <List>
795
    <Datagrid expand={<PostPanel />} expandSingle>
796
      <TextField source="title" />
797
      <TextField source="author" />
798
      <DateField source="published_at" />
799
    </Datagrid>
800
  </List>
801
);
802
```
803

804
### Custom Row Styles
805

806
```typescript
807
<Datagrid
808
  rowSx={record => ({
809
    backgroundColor: record.published ? '#e8f5e8' : '#fff2e8',
810
    '&:hover': {
811
      backgroundColor: record.published ? '#d4f5d4' : '#ffe4cc'
812
    }
813
  })}
814
  isRowSelectable={record => !record.archived}
815
>
816
  <TextField source="title" />
817
  <BooleanField source="published" />
818
</Datagrid>
819
```
820

821
### Responsive List
822

823
```typescript
824
import { List, SimpleList, Datagrid, useMediaQuery } from 'react-admin';
825

826
const PostList = () => {
827
  const isSmall = useMediaQuery((theme: any) => theme.breakpoints.down('sm'));
828
  
829
  return (
830
    <List>
831
      {isSmall ? (
832
        <SimpleList
833
          primaryText={record => record.title}
834
          secondaryText={record => `By ${record.author}`}
835
          tertiaryText={record => new Date(record.published_at).toLocaleDateString()}
836
        />
837
      ) : (
838
        <Datagrid>
839
          <TextField source="title" />
840
          <TextField source="author" />
841
          <DateField source="published_at" />
842
          <EditButton />
843
        </Datagrid>
844
      )}
845
    </List>
846
  );
847
};
848
```
849

850
React Admin's list and data display system provides comprehensive functionality for presenting collections of data in various formats, with powerful filtering, sorting, and interaction capabilities that scale from simple lists to complex data management interfaces.