Skip to content

Commit 4b20bec

Browse files
MadeorskMadeorsk
committed
Document standalone usage of WithListContext and fix error element property.
1 parent c44e43a commit 4b20bec

File tree

3 files changed

+85
-41
lines changed

3 files changed

+85
-41
lines changed

‎docs/WithListContext.md‎

Lines changed: 82 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -12,13 +12,13 @@ Use it to render a list of records already fetched.
1212

1313
## Usage
1414

15-
The most common use case for `<WithListContext>` is to build a custom list view on-the-fly, without creating a new component, in a place where records are available inside a `ListContext`.
15+
The most common use case for `<WithListContext>` is to build a custom list view on-the-fly, without creating a new component, in a place where records are available inside a `ListContext`.
1616

1717
For instance, a list of book tags fetched via [`<ReferenceArrayField>`](./ReferenceArrayField.md):
1818

1919
```jsx
2020
import { List, DataTable, ReferenceArrayField, WithListContext } from 'react-admin';
21-
import { Chip, Stack } from '@mui/material';
21+
import { Chip, Stack, Typography } from '@mui/material';
2222

2323
const BookList = () => (
2424
<List>
@@ -27,15 +27,18 @@ const BookList = () => (
2727
<DataTable.Col source="title" />
2828
<DataTable.Col source="tag_ids" label="Tags">
2929
<ReferenceArrayField reference="tags" source="tag_ids">
30-
<WithListContext render={({ isPending, data }) => (
31-
!isPending && (
30+
<WithListContext
31+
loading={<Typography>Loading tags...</Typography>}
32+
errorElement={<Typography>Error while loading tags</Typography>}
33+
empty={<Typography>No associated tags</Typography>}
34+
render={({ data }) => (
3235
<Stack direction="row" spacing={1}>
3336
{data.map(tag => (
3437
<Chip key={tag.id} label={tag.name} />
3538
))}
3639
</Stack>
37-
)
38-
)} />
40+
)}
41+
/>
3942
</ReferenceArrayField>
4043
</DataTable.Col>
4144
</DataTable>
@@ -45,10 +48,11 @@ const BookList = () => (
4548

4649
![List of tags](./img/reference-array-field.png)
4750

48-
The equivalent with `useListContext` would require an intermediate component:
51+
The equivalent with `useListContext` would require an intermediate component, manually handling the loading, error, and empty states:
4952

5053
```jsx
5154
import { List, DataTable, ReferenceArrayField, WithListContext } from 'react-admin';
55+
import { Chip, Stack, Typography } from '@mui/material';
5256

5357
const BookList = () => (
5458
<List>
@@ -65,31 +69,71 @@ const BookList = () => (
6569
);
6670

6771
const TagList = () => {
68-
const { isPending, data } = useListContext();
69-
return isPending
70-
? null
71-
: (
72-
<Stack direction="row" spacing={1}>
73-
{data.map(tag => (
74-
<Chip key={tag.id} label={tag.name} />
75-
))}
76-
</Stack>
77-
);
72+
const { isPending, error, data, total } = useListContext();
73+
74+
if (isPending) {
75+
return <Typography>Loading tags...</Typography>;
76+
}
77+
78+
if (error) {
79+
return <Typography>Error while loading tags</Typography>;
80+
}
81+
82+
if (data == null || data.length === 0 || total === 0) {
83+
return <Typography>No associated tags</Typography>;
84+
}
85+
86+
return (
87+
<Stack direction="row" spacing={1}>
88+
{data.map(tag => (
89+
<Chip key={tag.id} label={tag.name} />
90+
))}
91+
</Stack>
92+
);
7893
};
7994
```
8095

8196
Whether you use `<WithListContext>` or `useListContext` is a matter of coding style.
8297

98+
## Standalone usage
99+
100+
You can also use `<WithListContext>` outside of a `ListContext` by filling `data`, `total`, `error`, and `isPending` properties manually.
101+
102+
```jsx
103+
import { WithListContext } from 'react-admin';
104+
import { Chip, Stack, Typography } from '@mui/material';
105+
106+
const TagList = ({data, isPending}) => (
107+
<WithListContext
108+
data={data}
109+
isPending={isPending}
110+
loading={<Typography>Loading tags...</Typography>}
111+
empty={<Typography>No associated tags</Typography>}
112+
render={({ data }) => (
113+
<Stack direction="row" spacing={1}>
114+
{data.map(tag => (
115+
<Chip key={tag.id} label={tag.name} />
116+
))}
117+
</Stack>
118+
)}
119+
/>
120+
);
121+
```
122+
83123
## Props
84124

85125
`<WithListContext>` accepts a single `render` prop, which should be a function.
86126

87-
| Prop | Required | Type | Default | Description |
88-
|-----------|----------|----------------|---------|---------------------------------------------------------|
89-
| `empty` | Optional | `ReactElement` | | The component to display when the data is empty. |
90-
| `error` | Optional | `ReactElement` | | The component to display in case of error. |
91-
| `loading` | Optional | `ReactElement` | | The component to display while checking authorizations. |
92-
| `render` | Required | `function` | | The function to render the data |
127+
| Prop | Required | Type | Default | Description |
128+
|----------------|----------|----------------|---------|-----------------------------------------------------------|
129+
| `data` | Optional | `RecordType[]` | | The list data in standalone usage. |
130+
| `empty` | Optional | `ReactNode` | | The component to display when the data is empty. |
131+
| `error` | Optional | `Error` | | The error in standalone usage. |
132+
| `errorElement` | Optional | `ReactNode` | | The component to display in case of error. |
133+
| `isPending` | Optional | `boolean` | | Determine if the list is loading in standalone usage. |
134+
| `loading` | Optional | `ReactNode` | | The component to display while checking authorizations. |
135+
| `render` | Required | `function` | | The function to render the data |
136+
| `total` | Optional | `number` | | The total number of data in the list in standalone usage. |
93137

94138
## `empty`
95139

@@ -114,26 +158,26 @@ If `empty` is not provided, the render function will be called with empty data.
114158
/>
115159
```
116160

117-
## `error`
161+
## `errorElement`
118162

119-
Use `error` to display a message when an error is thrown.
163+
Use `errorElement` to display a message when an error is thrown.
120164

121-
If `error` is not provided, the render function will be called with the error.
165+
If `errorElement` is not provided, the render function will be called with the error.
122166

123167
```jsx
124168
<WithListContext
125-
error={<p>Error while loading books...</p>}
126-
render={({ data }) => (
127-
<ul>
128-
{data.map(book => (
129-
<li key={book.id}>
130-
<i>{book.title}</i>, published on
131-
{book.published_at}
132-
</li>
133-
))}
134-
</ul>
135-
)}
136-
loading={<p>Loading...</p>}
169+
errorElement={<p>Error while loading books...</p>}
170+
render={({ data }) => (
171+
<ul>
172+
{data.map(book => (
173+
<li key={book.id}>
174+
<i>{book.title}</i>, published on
175+
{book.published_at}
176+
</li>
177+
))}
178+
</ul>
179+
)}
180+
loading={<p>Loading...</p>}
137181
/>
138182
```
139183

‎packages/ra-core/src/controller/list/WithListContext.stories.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -323,7 +323,7 @@ export const Error = () => (
323323
<CoreAdminContext dataProvider={erroredDataProvider}>
324324
<ListBase resource="fruits" disableSyncWithLocation perPage={100}>
325325
<WithListContext<Fruit>
326-
error={<p>Error loading data</p>}
326+
errorElement={<p>Error loading data</p>}
327327
render={({ isPending, data, total }) =>
328328
isPending ? (
329329
<>Loading...</>

‎packages/ra-core/src/controller/list/WithListContext.tsx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ import { useListContextWithProps } from './useListContextWithProps';
2222
export const WithListContext = <RecordType extends RaRecord>({
2323
empty,
2424
loading,
25-
error: errorElement,
25+
errorElement,
2626
render,
2727
...props
2828
}: WithListContextProps<RecordType>) => {
@@ -55,5 +55,5 @@ export type WithListContextProps<RecordType extends RaRecord> = Partial<
5555
) => ReactElement | false | null;
5656
empty?: React.ReactNode;
5757
loading?: React.ReactNode;
58-
error?: React.ReactNode;
58+
errorElement?: React.ReactNode;
5959
};

0 commit comments

Comments
 (0)