--- layout: default title: "The ReferenceArrayField Component" storybook_path: ra-ui-materialui-fields-referencearrayfield--basic --- # `` Use `` to display a list of related records, via a one-to-many relationship materialized by an array of foreign keys. `` fetches a list of referenced records (using the `dataProvider.getMany()` method), and puts them in a [`ListContext`](./useListContext.md). It then renders each related record, using its [`recordRepresentation`](./Resource.md#recordrepresentation), in a [``](./ChipField.md). **Tip**: If the relationship is materialized by a foreign key on the referenced resource, use [the `` component](./ReferenceManyField.md) instead. **Tip**: To edit the records of a one-to-many relationship, use [the `` component](./ReferenceArrayInput.md). ## Usage For instance, let's consider a model where a `post` has many `tags`, materialized to a `tags_ids` field containing an array of ids: ``` ┌──────────────┐ ┌────────┐ │ posts │ │ tags │ │--------------│ │--------│ │ id │ ┌───│ id │ │ title │ │ │ name │ │ body │ │ └────────┘ │ is_published │ │ │ tag_ids │╾──┘ └──────────────┘ ``` A typical `post` record therefore looks like this: ```json { "id": 1, "title": "Hello world", "body": "...", "is_published": true, "tags_ids": [1, 2, 3] } ``` In that case, use `` to display the post tag names as Chips as follows: ```jsx import { List, DataTable, ReferenceArrayField } from 'react-admin'; export const PostList = () => ( ); ``` ![ReferenceArrayField](./img/reference-array-field.png) `` 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. `` fetches the `tag` resources related to each `post` resource by matching `post.tag_ids` to `tag.id`. By default, it renders one string by related record, via a [``](./SingleFieldList.md) with a [``](./ChipField.md) child using the resource [`recordRepresentation`](./Resource.md#recordrepresentation) as source Configure the `` to render related records in a meaningful way. For instance, for the `tags` resource, if you want the `` to display the tag `name`: ```jsx ``` You can change how the list of related records is rendered by passing a custom child reading the `ListContext` (e.g. a [``](./DataTable.md)). See the [`children`](#children) section for details. ## Props | Prop | Required | Type | Default | Description | | -------------- | -------- | --------------------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------ | | `source` | Required | `string` | - | Name of the property to display | | `reference` | Required | `string` | - | The name of the resource for the referenced records, e.g. 'tags' | | `children` | Optional * | `ReactNode` | `` | One or several elements that render a list of records based on a `ListContext` | | `render` | Optional * | `(listContext) => Element` | `` | A function that takes a list context and render a list of records | | `empty` | Optional | `ReactNode` | - | The component to render when the related records list is empty | | `error` | Optional | `ReactNode` | - | The component to render when an error occurs while fetching the related records | | `filter` | Optional | `Object` | - | Filters to use when fetching the related records (the filtering is done client-side) | | `exporter` | Optional | `function` | `defaultExporter` | The function called by export buttons in the list context | | `loading` | Optional | `ReactNode` | `` | The component to render while fetching the related records | | `offline` | Optional | `ReactNode` | `` | The component to render when there is no connectivity and the record isn't in the cache | | `pagination` | Optional | `ReactNode` | - | Pagination element to display pagination controls. empty by default (no pagination) | | `perPage` | Optional | `number` | 1000 | Maximum number of results to display | | `queryOptions` | Optional | [`UseQuery Options`](https://tanstack.com/query/v5/docs/react/reference/useQuery) | `{}` | `react-query` options for the `getMany` query | | `sort` | Optional | `{ field, order }` | `{ field: 'id', order: 'DESC' }` | Sort order to use when displaying the related records (the sort is done client-side) | | `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. | `*` You must provide either `children` or `render`. `` also accepts the [common field props](./Fields.md#common-field-props), except `emptyText` (use the child `empty` prop instead). ## `children` By default, `` renders one string by related record, via a [``](./SingleFieldList.md) with a [``](./ChipField.md) using the resource [`recordRepresentation`](./Resource.md#recordrepresentation). ![ReferenceArrayField with default children](./img/ReferenceArrayField-default-child.png) You can pass any component of your own as child, to render the list of related records in another way. That means that using the field without child: ```jsx ``` Is equivalent to: ```jsx ``` `` creates a [`ListContext`](./useListContext.md), so you can use any child that uses a `ListContext`: - [``](./SingleFieldList.md) - [``](./DataTable.md) - [``](./Datagrid.md) - [``](./SimpleList.md) - [``](./EditableDatagrid.md) - [``](./Calendar.md) - Or a component of your own (check the [``](./WithListContext.md) and the [`useListContext`](./useListContext.md) chapters to learn how). For instance, use a `` to render the related records in a table: ```jsx import { Show, SimpleShowLayout, TextField, ReferenceArrayField, DataTable, ShowButton } from 'react-admin'; export const PostShow = () => ( ); ``` Alternatively, you can use [the `render` prop](#render) to render the related records in a custom way: ```tsx import { Show, SimpleShowLayout, TextField, ReferenceArrayField } from 'react-admin'; export const PostShow = () => ( (

{tag.name}

)} /> ); ``` ## `empty` By default, `` renders its children when the related records list is empty. You can customize what is rendered by providing your own component via the `empty` prop: ```jsx import { ReferenceArrayField, Show, SimpleShowLayout } from 'react-admin'; export const PostShow = () => ( No tags found.

} /> ); ``` You can also have `` render nothing in that case by setting the prop to `null`: ```jsx ``` ## `error` By default, `` renders its children when an error occurs while fetching the related records. You can customize what is rendered by providing your own component via the `error` prop: ```jsx import { ReferenceArrayField, Show, SimpleShowLayout } from 'react-admin'; export const PostShow = () => ( Error loading tags. Please try again.

} /> ); ``` You can also have `` render nothing in that case by setting the prop to `null`: ```jsx ``` ## `filter` `` 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). For instance, to render only tags that are 'published', you can use the following code: {% raw %} ```jsx ``` {% endraw %} ## `label` By default, ``, `` and other layout components infer the label of a field based on its `source`. For a ``, this may not be what you expect: ```jsx {/* default label is 'Tag Ids', or the translation of 'resources.posts.fields.tag_ids' if it exists */} ``` That's why you often need to set an explicit `label` on a ``: ```jsx ``` **Tip**: Having to specify the `label` prop on the field for it to be used by the Datagrid is no longer necessary with [``](./DataTable.md), the successor of the `` component. Instead, `` properly separates the props for the column header and the field itself, thanks to the [``](./DataTable.md#datatablecol) component. React-admin uses [the i18n system](./Translation.md) to translate the label, so you can use translation keys to have one label for each language supported by the interface: ```jsx ``` ## `loading` By default, `` renders a `` component while fetching the related records. You can customize what is rendered by providing your own component via the `loading` prop: ```jsx import { ReferenceArrayField, Show, SimpleShowLayout } from 'react-admin'; import { CircularProgress } from '@mui/material'; export const PostShow = () => ( } /> ); ``` You can also have `` render nothing in that case by setting the prop to `null`: ```jsx ``` ## `offline` By default, `` renders the `` when there is no connectivity and the records haven't been cached yet. You can provide your own component via the `offline` prop: ```jsx import { ReferenceArrayField, Show } from 'react-admin'; import { Alert } from '@mui/material'; export const PostShow = () => ( No network. Could not load the tags.} > ... ); ``` **Tip**: If the records are in the Tanstack Query cache but you want to warn the user that they may see an outdated version, you can use the `` component: ```jsx import { IsOffline, ReferenceArrayField, Show } from 'react-admin'; import { Alert } from '@mui/material'; export const PostShow = () => ( You are offline, tags may be outdated ... ); ``` ## `pagination` `` fetches *all* the related fields, and puts them all in a `ListContext`. If a record has a large number of related records, you can limit the number of displayed records with the [`perPage`](#perpage) prop. Then, let users display remaining records by rendering pagination controls. For that purpose, pass a pagination element to the `pagination` prop. For instance, to limit the display of related records to 10, you can use the following code: ```jsx import { Pagination, ReferenceArrayField } from 'react-admin'; } /> ``` ## `perPage` `` 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. For instance, to limit the display of related records to 10, you can use the following code: ```jsx ``` If you want to let the user display the remaining records, you have to pass a [`pagination`](#pagination) element. ## `queryOptions` Use the `queryOptions` prop to pass options to [the `dataProvider.getMany()` query](./useGetOne.md#aggregating-getone-calls) that fetches the referenced record. For instance, to pass [a custom `meta`](./Actions.md#meta-parameter): {% raw %} ```jsx ``` {% endraw %} ## `render` Alternatively to `children`, you can pass a `render` prop to ``. It will receive the [`ListContext`](./useListContext.md#return-value) as its argument, and should return a React node. This allows to inline the render logic for the list of related records. ```jsx { if (isPending) { return

; } if (error) { return

{error.toString()}

; } return (

{tag.name}

); }} /> ``` ## `reference` The resource to fetch for the relateds record. For instance, if the `posts` resource has a `tag_ids` field, set the `reference` to `tags` to fetch the tags related to each post. ```jsx ``` ## `sort` 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 `` on the `tag_ids` field will display tags in the order 1, 23, 4. `` can force a different order (via a client-side sort after fetch) if you specify a `sort` prop. For instance, to sort tags by title in ascending order, you can use the following code: {% raw %} ```jsx ``` {% endraw %} ## `sx`: CSS API The `` component accepts the usual `className` prop. You can also override many styles of the inner components thanks to the `sx` property (see [the `sx` documentation](./SX.md) for syntax and examples). This property accepts the following subclasses: | Rule name | Description | |-------------------------------------|------------------------------------------------------------------------------------------| | `& .RaReferenceArrayField-progress` | Applied to the Material UI's `LinearProgress` component while `isPending` prop is `true` | To override the style of all instances of `` using the [application-wide style overrides](./AppTheme.md#theming-individual-components), use the `RaReferenceArrayField` key.