You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: docs/ArrayField.md
+176-15
Original file line number
Diff line number
Diff line change
@@ -5,17 +5,21 @@ title: "The ArrayField Component"
5
5
6
6
# `<ArrayField>`
7
7
8
-
Display a collection using `<Field>`child components.
8
+
`<ArrayField>`renders an embedded array of objects.
9
9
10
-
Ideal for embedded arrays of objects, e.g. `tags` and `backlinks` in the following `post` object:
10
+
11
+
12
+
`<ArrayField>` creates a [`ListContext`](./useListContext.md) with the field value, and renders its children components - usually iterator components like [`<Datagrid>`](./Datagrid.md) or [`<SingleFieldList>`](./SingleFieldList.md).
13
+
14
+
## Usage
15
+
16
+
`<ArrayField>` is ideal for collections of objects, e.g. `tags` and `backlinks` in the following `post` object:
|`children`| Required |`ReactNode`|| The component to render the list. |
77
+
|`filter`| Optional |`object`|| The filter to apply to the list. |
78
+
|`perPage`| Optional |`number`| 1000 | The number of items to display per page. |
79
+
|`sort`| Optional |`{ field, order}`|| The sort to apply to the list. |
80
+
81
+
`<ArrayField>` accepts the [common field props](./Fields.md#common-field-props), except `emptyText` (use the child `empty` prop instead).
82
+
83
+
`<ArrayField>` relies on [`useList`](./useList.md) to filter, paginate, and sort the data, so it accepts the same props.
84
+
85
+
## `children`
35
86
36
-
Here is how to display all the backlinks of the current post as a `<Datagrid>`:
87
+
`<ArrayField>` renders its `children` component wrapped in a [`<ListContextProvider>`](./useListContext.md). Commonly used child components are [`<Datagrid>`](./Datagrid.md), [`<SingleFieldList>`](./SingleFieldList.md), and [`<SimpleList>`](./SimpleList.md).
37
88
38
89
```jsx
90
+
{/* using SingleFieldList as child */}
91
+
<ArrayField source="tags">
92
+
<SingleFieldList>
93
+
<ChipField source="name"/>
94
+
</SingleFieldList>
95
+
</ArrayField>
96
+
97
+
{/* using Datagrid as child */}
39
98
<ArrayField source="backlinks">
40
99
<Datagrid>
41
-
<DateField source="date"/>
42
-
<UrlField source="url"/>
100
+
<TextField source="uuid"/>
101
+
<TextField source="date"/>
102
+
<TextField source="url"/>
43
103
</Datagrid>
44
104
</ArrayField>
105
+
106
+
{/* using SimpleList as child */}
107
+
<ArrayField source="backlinks">
108
+
<SimpleList
109
+
primaryText={record=>record.url}
110
+
secondaryText={record=>record.date}
111
+
/>
112
+
</ArrayField>
45
113
```
46
114
47
-
And here is how to display all the tags of the current post as `<Chip>` components:
115
+
## `filter`
116
+
117
+
You can use the `filter` prop to display only a subset of the items in the array. For instance, to display only the backlinks for a particular day:
The filtering capabilities are very limited. For instance, there is no "greater than" or "less than" operator. You can only filter on the equality of a field.
132
+
133
+
## `perPage`
134
+
135
+
If the value is a large array, and you don't need to display all the items, you can use the `perPage` prop to limit the number of items displayed.
136
+
137
+
As `<ArrayField>` creates a [`ListContext`](./useListContext.md), you can use the `<Pagination>` component to navigate through the items.
138
+
139
+
```jsx
140
+
import {
141
+
ArrayField,
142
+
Datagrid,
143
+
Pagination,
144
+
Show,
145
+
SimpleShowLayout,
146
+
TextField
147
+
} from'react-admin';
148
+
149
+
constPostShow= () => (
150
+
<Show>
151
+
<SimpleShowLayout>
152
+
<TextField source="title"/>
153
+
<ArrayField source="backlinks" perPage={5}>
154
+
<Datagrid>
155
+
<TextField source="uuid"/>
156
+
<TextField source="date"/>
157
+
<TextField source="url"/>
158
+
</Datagrid>
159
+
<Pagination />
160
+
</ArrayField>
161
+
</SimpleShowLayout>
162
+
</Show>
163
+
);
164
+
```
165
+
166
+
## `sort`
167
+
168
+
By default, `<ArrayField>` displays the items in the order they are stored in the field. You can use the `sort` prop to change the sort order.
`<ArrayField>` accepts the [common field props](./Fields.md#common-field-props), except `emptyText` (use the child `empty` prop instead).
182
+
`<ArrayField>` creates a [`ListContext`](./useListContext.md) with the field value, so you can use any of the list context values in its children. This includes callbacks to sort, filter, and select items.
183
+
184
+
For instance, you can make the chips selectable as follows:
**Tip**: The selection logic uses the `id` field for each collection element, so the above example assumes that the `tags` field contains objects like `{ id: 123, name: 'bar' }`.
217
+
218
+
Check [the `useListContext` documentation](./useListContext.md) for more information on the list context values.
219
+
220
+
## Rendering An Array Of Strings
60
221
61
-
**Tip**: If you need to render a custom collection, it's often simpler to write your own component:
222
+
If you need to render a custom collection (e.g. an array of tags `['dolor', 'sit', 'amet']`), it's often simpler to write your own component:
// data will be [{ id: 1, name: 'Arnold' }] and total will be 1
104
104
```
105
105
106
+
The filtering capabilities are very limited. For instance, there is no "greater than" or "less than" operator. You can only filter on the equality of a field.
107
+
106
108
## `filterCallback`
107
109
108
110
Property for custom filter definition. Lets you apply local filters to the fetched data.
0 commit comments