|
| 1 | +--- |
| 2 | +layout: default |
| 3 | +title: "The ReferenceArrayFieldBase Component" |
| 4 | +storybook_path: ra-core-fields-referencearrayfieldbase--basic |
| 5 | +--- |
| 6 | + |
| 7 | +# `<ReferenceArrayFieldBase>` |
| 8 | + |
| 9 | +Use `<ReferenceArrayFieldBase>` to display a list of related records, via a one-to-many relationship materialized by an array of foreign keys. |
| 10 | + |
| 11 | +`<ReferenceArrayFieldBase>` fetches a list of referenced records (using the `dataProvider.getMany()` method), and puts them in a [`ListContext`](./useListContext.md). This component is headless, and its children need to use the data from this context to render the desired ui. |
| 12 | + |
| 13 | +**Tip**: For a rendering a list of chips by default, use [the `<ReferenceArrayField>` component](./ReferenceArrayField.md) instead. |
| 14 | + |
| 15 | +**Tip**: If the relationship is materialized by a foreign key on the referenced resource, use [the `<ReferenceManyFieldBase>` component](./ReferenceManyFieldBase.md) instead. |
| 16 | + |
| 17 | +## Usage |
| 18 | + |
| 19 | +For instance, let's consider a model where a `post` has many `tags`, materialized to a `tags_ids` field containing an array of ids: |
| 20 | + |
| 21 | +``` |
| 22 | +┌──────────────┐ ┌────────┐ |
| 23 | +│ posts │ │ tags │ |
| 24 | +│--------------│ │--------│ |
| 25 | +│ id │ ┌───│ id │ |
| 26 | +│ title │ │ │ name │ |
| 27 | +│ body │ │ └────────┘ |
| 28 | +│ is_published │ │ |
| 29 | +│ tag_ids │╾──┘ |
| 30 | +└──────────────┘ |
| 31 | +``` |
| 32 | + |
| 33 | +A typical `post` record therefore looks like this: |
| 34 | + |
| 35 | +```json |
| 36 | +{ |
| 37 | + "id": 1, |
| 38 | + "title": "Hello world", |
| 39 | + "body": "...", |
| 40 | + "is_published": true, |
| 41 | + "tags_ids": [1, 2, 3] |
| 42 | +} |
| 43 | +``` |
| 44 | + |
| 45 | +In that case, use `<ReferenceArrayFieldBase>` to display the post tag names as a list of chips, as follows: |
| 46 | + |
| 47 | +```jsx |
| 48 | +import { ListBase, ListIterator, ReferenceArrayFieldBase } from 'react-admin'; |
| 49 | + |
| 50 | +export const PostList = () => ( |
| 51 | + <ListBase> |
| 52 | + <ListIterator> |
| 53 | + <ReferenceArrayFieldBase reference="tags" source="tag_ids"> |
| 54 | + <TagList /> |
| 55 | + </ReferenceArrayFieldBase> |
| 56 | + </ListIterator> |
| 57 | + </ListBase> |
| 58 | +); |
| 59 | + |
| 60 | +const TagList = (props: { children: React.ReactNode }) => { |
| 61 | + const context = useListContext(); |
| 62 | + |
| 63 | + if (context.isPending) { |
| 64 | + return <p>Loading...</p>; |
| 65 | + } |
| 66 | + |
| 67 | + if (context.error) { |
| 68 | + return <p className="error">{context.error.toString()}</p>; |
| 69 | + } |
| 70 | + return ( |
| 71 | + <p> |
| 72 | + {listContext.data?.map((tag, index) => ( |
| 73 | + <li key={index}>{tag.name}</li> |
| 74 | + ))} |
| 75 | + </p> |
| 76 | + ); |
| 77 | +}; |
| 78 | +``` |
| 79 | +
|
| 80 | +`<ReferenceArrayFieldBase>` expects a `reference` attribute, which specifies the resource to fetch for the related records. It also expects a `source` attribute, which defines the field containing the list of ids to look for in the referenced resource. |
| 81 | +
|
| 82 | +`<ReferenceArrayFieldBase>` fetches the `tag` resources related to each `post` resource by matching `post.tag_ids` to `tag.id`. |
| 83 | +
|
| 84 | +You can change how the list of related records is rendered by passing a custom child reading the `ListContext` (e.g. a [`<DataTable>`](./DataTable.md)) or a render function prop. See the [`children`](#children) and the [`render`](#render) sections for details. |
| 85 | +
|
| 86 | +## Props |
| 87 | +
|
| 88 | +| Prop | Required | Type | Default | Description | |
| 89 | +| -------------- | -------- | --------------------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------ | |
| 90 | +| `source` | Required | `string` | - | Name of the property to display | |
| 91 | +| `reference` | Required | `string` | - | The name of the resource for the referenced records, e.g. 'tags' | |
| 92 | +| `children` | Optional\* | `Element` | | One or several elements that render a list of records based on a `ListContext` | |
| 93 | +| `render` | Optional\* | `(ListContext) => Element` | | A function that takes a list context and renders a list of records | |
| 94 | +| `filter` | Optional | `Object` | - | Filters to use when fetching the related records (the filtering is done client-side) | |
| 95 | +| `perPage` | Optional | `number` | 1000 | Maximum number of results to display | |
| 96 | +| `queryOptions` | Optional | [`UseQuery Options`](https://tanstack.com/query/v5/docs/react/reference/useQuery) | `{}` | `react-query` options for the `getMany` query | |
| 97 | +| `sort` | Optional | `{ field, order }` | `{ field: 'id', order: 'DESC' }` | Sort order to use when displaying the related records (the sort is done client-side) | |
| 98 | +| `sortBy` | Optional | `string | Function` | `source` | When used in a `List`, name of the field to use for sorting when the user clicks on the column header. | |
| 99 | +
|
| 100 | +\* Either one of children or render is required. |
| 101 | +
|
| 102 | +## `children` |
| 103 | +
|
| 104 | +You can pass any React component as child, to render the list of related records based on the `ListContext`. |
| 105 | +
|
| 106 | +```jsx |
| 107 | +<ReferenceArrayFieldBase label="Tags" reference="tags" source="tag_ids"> |
| 108 | + <TagList /> |
| 109 | +</ReferenceArrayFieldBase> |
| 110 | + |
| 111 | +const TagList = (props: { children: React.ReactNode }) => { |
| 112 | + const { isPending, error, data } = useListContext(); |
| 113 | + |
| 114 | + if (isPending) { |
| 115 | + return <p>Loading...</p>; |
| 116 | + } |
| 117 | + |
| 118 | + if (error) { |
| 119 | + return <p className="error">{error.toString()}</p>; |
| 120 | + } |
| 121 | + return ( |
| 122 | + <p> |
| 123 | + {data?.map((tag, index) => ( |
| 124 | + <li key={index}>{tag.name}</li> |
| 125 | + ))} |
| 126 | + </p> |
| 127 | + ); |
| 128 | +}; |
| 129 | +``` |
| 130 | +
|
| 131 | +## `render` |
| 132 | +
|
| 133 | +Alternatively to `children`, you can pass a `render` function prop to `<ReferenceArrayFieldBase>`. The `render` prop will receive the `ListContext` as its argument, allowing to inline the rendering logic. |
| 134 | +
|
| 135 | +```jsx |
| 136 | +<ReferenceArrayFieldBase |
| 137 | + label="Tags" |
| 138 | + reference="tags" |
| 139 | + source="tag_ids" |
| 140 | + render={({ isPending, error, data }) => { |
| 141 | + if (isPending) { |
| 142 | + return <p>Loading...</p>; |
| 143 | + } |
| 144 | + if (error) { |
| 145 | + return <p className="error">{error.toString()}</p>; |
| 146 | + } |
| 147 | + return ( |
| 148 | + <p> |
| 149 | + {data.map((tag, index) => ( |
| 150 | + <li key={index}>{tag.name}</li> |
| 151 | + ))} |
| 152 | + </p> |
| 153 | + ); |
| 154 | + }} |
| 155 | +/> |
| 156 | +``` |
| 157 | +
|
| 158 | +**Tip**: When receiving a `render` prop, the `<ReferenceArrayFieldBase>` component will ignore the `children` property. |
| 159 | +
|
| 160 | +## `filter` |
| 161 | +
|
| 162 | +`<ReferenceArrayFieldBase>` fetches all the related records, and displays them all, too. You can use the `filter` prop to filter the list of related records to display (this works by filtering the records client-side, after the fetch). |
| 163 | +
|
| 164 | +For instance, to render only tags that are 'published', you can use the following code: |
| 165 | +
|
| 166 | +{% raw %} |
| 167 | +```jsx |
| 168 | +<ReferenceArrayFieldBase |
| 169 | + label="Tags" |
| 170 | + source="tag_ids" |
| 171 | + reference="tags" |
| 172 | + filter={{ is_published: true }} |
| 173 | +/> |
| 174 | +``` |
| 175 | +{% endraw %} |
| 176 | +
|
| 177 | +## `perPage` |
| 178 | +
|
| 179 | +`<ReferenceArrayFieldBase>` fetches *all* the related fields, and puts them all in a `ListContext`. If a record has a large number of related records, it may be a good idea to limit the number of displayed records. The `perPage` prop allows to create a client-side pagination for the related records. |
| 180 | +
|
| 181 | +For instance, to limit the display of related records to 10, you can use the following code: |
| 182 | +
|
| 183 | +```jsx |
| 184 | + <ReferenceArrayFieldBase label="Tags" source="tag_ids" reference="tags" perPage={10} /> |
| 185 | +``` |
| 186 | +
|
| 187 | +## `queryOptions` |
| 188 | +
|
| 189 | +Use the `queryOptions` prop to pass options to [the `dataProvider.getMany()` query](./useGetOne.md#aggregating-getone-calls) that fetches the referenced record. |
| 190 | +
|
| 191 | +For instance, to pass [a custom `meta`](./Actions.md#meta-parameter): |
| 192 | +
|
| 193 | +{% raw %} |
| 194 | +```jsx |
| 195 | +<ReferenceArrayFieldBase queryOptions={{ meta: { foo: 'bar' } }} /> |
| 196 | +``` |
| 197 | +{% endraw %} |
| 198 | +
|
| 199 | +## `reference` |
| 200 | +
|
| 201 | +The resource to fetch for the relateds record. |
| 202 | +
|
| 203 | +For instance, if the `posts` resource has a `tag_ids` field, set the `reference` to `tags` to fetch the tags related to each post. |
| 204 | +
|
| 205 | +```jsx |
| 206 | +<ReferenceArrayFieldBase label="Tags" source="tag_ids" reference="tags" /> |
| 207 | +``` |
| 208 | +
|
| 209 | +## `sort` |
| 210 | +
|
| 211 | +By default, the related records are displayed in the order in which they appear in the `source`. For instance, if the current record is `{ id: 1234, title: 'Lorem Ipsum', tag_ids: [1, 23, 4] }`, a `<ReferenceArrayFieldBase>` on the `tag_ids` field will display tags in the order 1, 23, 4. |
| 212 | +
|
| 213 | +`<ReferenceArrayFieldBase>` can force a different order (via a client-side sort after fetch) if you specify a `sort` prop. |
| 214 | +
|
| 215 | +For instance, to sort tags by title in ascending order, you can use the following code: |
| 216 | +
|
| 217 | +{% raw %} |
| 218 | +```jsx |
| 219 | +<ReferenceArrayFieldBase |
| 220 | + label="Tags" |
| 221 | + source="tag_ids" |
| 222 | + reference="tags" |
| 223 | + sort={{ field: 'title', order: 'ASC' }} |
| 224 | +/> |
| 225 | +``` |
| 226 | +{% endraw %} |
0 commit comments