|
| 1 | +--- |
| 2 | +layout: default |
| 3 | +title: "The InfiniteList Component" |
| 4 | +--- |
| 5 | + |
| 6 | +# `<InfiniteList>` |
| 7 | + |
| 8 | +The `<InfiniteList>` component is an alternative to [the `<List>` component](./List.md) that allows user to load more records when they scroll to the bottom of the list. It's useful when you have a large number of records, or when users are using a mobile device. |
| 9 | + |
| 10 | +<video controls autoplay muted loop width="100%"> |
| 11 | + <source src="./img/infinite-book-list.webm" poster="./img/infinite-book-list.webp" type="video/webm"> |
| 12 | + Your browser does not support the video tag. |
| 13 | +</video> |
| 14 | + |
| 15 | +`<InfiniteList>` fetches the list of records from the data provider, and renders the default list layout (title, buttons, filters). It delegates the rendering of the list of records to its child component. Usually, it's a [`<Datagrid>`](./Datagrid.md) or a [`<SimpleList>`](./SimpleList.md), responsible for displaying a table with one row for each record. |
| 16 | + |
| 17 | +## Usage |
| 18 | + |
| 19 | +Here is the minimal code necessary to display a list of books with infinite scroll: |
| 20 | + |
| 21 | +```jsx |
| 22 | +// in src/books.js |
| 23 | +import { InfiniteList, Datagrid, TextField, DateField } from 'react-admin'; |
| 24 | + |
| 25 | +export const BookList = () => ( |
| 26 | + <InfiniteList> |
| 27 | + <Datagrid> |
| 28 | + <TextField source="id" /> |
| 29 | + <TextField source="title" /> |
| 30 | + <DateField source="author" /> |
| 31 | + </Datagrid> |
| 32 | + </InfiniteList> |
| 33 | +); |
| 34 | + |
| 35 | +// in src/App.js |
| 36 | +import { Admin, Resource } from 'react-admin'; |
| 37 | +import jsonServerProvider from 'ra-data-json-server'; |
| 38 | + |
| 39 | +import { BookList } from './books'; |
| 40 | + |
| 41 | +const App = () => ( |
| 42 | + <Admin dataProvider={jsonServerProvider('https://jsonplaceholder.typicode.com')}> |
| 43 | + <Resource name="books" list={BookList} /> |
| 44 | + </Admin> |
| 45 | +); |
| 46 | + |
| 47 | +export default App; |
| 48 | +``` |
| 49 | + |
| 50 | +That's enough to display a basic post list, that users can sort and filter, and load additional records when they reach the bottom of the list. |
| 51 | + |
| 52 | +**Tip**: `<Datagrid>` has a sticky header by default, so the user can always see the column names when they scroll down. |
| 53 | + |
| 54 | +## Props |
| 55 | + |
| 56 | +The props are the same as [the `<List>` component](./List.md): |
| 57 | + |
| 58 | +| Prop | Required | Type | Default | Description | |
| 59 | +|----------------------------|----------|----------------|-------------------------|----------------------------------------------------------------------------------------------| |
| 60 | +| `children` | Required | `ReactNode` | - | The component to use to render the list of records. | |
| 61 | +| `actions` | Optional | `ReactElement` | - | The actions to display in the toolbar. | |
| 62 | +| `aside` | Optional | `ReactElement` | - | The component to display on the side of the list. | |
| 63 | +| `component` | Optional | `Component` | `Card` | The component to render as the root element. | |
| 64 | +| `debounce` | Optional | `number` | `500` | The debounce delay in milliseconds to apply when users change the sort or filter parameters. | |
| 65 | +| `disable Authentication` | Optional | `boolean` | `false` | Set to `true` to disable the authentication check. | |
| 66 | +| `disable SyncWithLocation` | Optional | `boolean` | `false` | Set to `true` to disable the synchronization of the list parameters with the URL. | |
| 67 | +| `empty` | Optional | `ReactElement` | - | The component to display when the list is empty. | |
| 68 | +| `empty WhileLoading` | Optional | `boolean` | `false` | Set to `true` to return `null` while the list is loading. | |
| 69 | +| `exporter` | Optional | `function` | - | The function to call to export the list. | |
| 70 | +| `filters` | Optional | `ReactElement` | - | The filters to display in the toolbar. | |
| 71 | +| `filter` | Optional | `object` | - | The permanent filter values. | |
| 72 | +| `filter DefaultValues` | Optional | `object` | - | The default filter values. | |
| 73 | +| `hasCreate` | Optional | `boolean` | `false` | Set to `true` to show the create button. | |
| 74 | +| `pagination` | Optional | `ReactElement` | `<Infinite Pagination>` | The pagination component to use. | |
| 75 | +| `perPage` | Optional | `number` | `10` | The number of records to fetch per page. | |
| 76 | +| `queryOptions` | Optional | `object` | - | The options to pass to the `useQuery` hook. | |
| 77 | +| `resource` | Optional | `string` | - | The resource name, e.g. `posts`. | |
| 78 | +| `sort` | Optional | `object` | - | The initial sort parameters. | |
| 79 | +| `storeKey` | Optional | `string` | - | The key to use to store the current filter & sort. | |
| 80 | +| `title` | Optional | `string` | - | The title to display in the App Bar. | |
| 81 | +| `sx` | Optional | `object` | - | The CSS styles to apply to the component. | |
| 82 | + |
| 83 | +Check the [`<List>` component](./List.md) for details about each prop. |
| 84 | + |
| 85 | +Additional props are passed down to the root component (a MUI `<Card>` by default). |
| 86 | + |
| 87 | +## `pagination` |
| 88 | + |
| 89 | +You can replace the default "load on scroll" pagination (triggered by a component named `<InfinitePagination>`) by a custom pagination component. To get the pagination state and callbacks, you'll need to read the `InfinitePaginationContext`. |
| 90 | + |
| 91 | + |
| 92 | + |
| 93 | +For example, here is a custom infinite pagination component displaying a "Load More" button at the bottom of the list: |
| 94 | + |
| 95 | +```jsx |
| 96 | +import { InfiniteList, useInfinitePaginationContext, Datagrid, TextField } from 'react-admin'; |
| 97 | +import { Box, Button } from '@mui/material'; |
| 98 | + |
| 99 | +const LoadMore = () => { |
| 100 | + const { |
| 101 | + hasNextPage, |
| 102 | + fetchNextPage, |
| 103 | + isFetchingNextPage, |
| 104 | + } = useInfinitePaginationContext(); |
| 105 | + return hasNextPage ? ( |
| 106 | + <Box mt={1} textAlign="center"> |
| 107 | + <Button |
| 108 | + disabled={isFetchingNextPage} |
| 109 | + onClick={() => fetchNextPage()} |
| 110 | + > |
| 111 | + Load more |
| 112 | + </Button> |
| 113 | + </Box> |
| 114 | + ) : null; |
| 115 | +}; |
| 116 | + |
| 117 | +export const BookList = () => ( |
| 118 | + <InfiniteList pagination={<LoadMore />}> |
| 119 | + <Datagrid> |
| 120 | + <TextField source="id" /> |
| 121 | + <TextField source="title" /> |
| 122 | + <TextField source="author" /> |
| 123 | + </Datagrid> |
| 124 | + </InfiniteList> |
| 125 | +); |
| 126 | +``` |
| 127 | + |
| 128 | +## Showing The Record Count |
| 129 | + |
| 130 | +One drawback of the `<InfiniteList>` component is that it doesn't show the number of results. To fix this, you can use `useListContext` to access the `total` property of the list, and render the total number of results in a sticky footer: |
| 131 | + |
| 132 | + |
| 133 | + |
| 134 | +{% raw %} |
| 135 | +```jsx |
| 136 | +import { useListContext, InfinitePagination, InfiniteList } from 'react-admin'; |
| 137 | +import { Box, Card, Typography } from '@mui/material'; |
| 138 | + |
| 139 | +const CustomPagination = () => { |
| 140 | + const { total } = useListContext(); |
| 141 | + return ( |
| 142 | + <> |
| 143 | + <InfinitePagination /> |
| 144 | + {total > 0 && ( |
| 145 | + <Box position="sticky" bottom={0} textAlign="center"> |
| 146 | + <Card |
| 147 | + elevation={2} |
| 148 | + sx={{ px: 2, py: 1, mb: 1, display: 'inline-block' }} |
| 149 | + > |
| 150 | + <Typography variant="body2">{total} results</Typography> |
| 151 | + </Card> |
| 152 | + </Box> |
| 153 | + )} |
| 154 | + </> |
| 155 | + ); |
| 156 | +}; |
| 157 | + |
| 158 | +export const BookList = () => ( |
| 159 | + <InfiniteList pagination={<CustomPagination />}> |
| 160 | + // ... |
| 161 | + </InfiniteList> |
| 162 | +); |
| 163 | +``` |
| 164 | +{% endraw %} |
0 commit comments