--- layout: default title: "The ReferenceOneField Component" storybook_path: ra-ui-materialui-fields-referenceonefield--basic --- # `` This field fetches a one-to-one relationship, e.g. the details of a book, when using a foreign key on the distant resource. ``` ┌──────────────┐ ┌──────────────┐ │ books │ │ book_details │ │--------------│ │--------------│ │ id │───┐ │ id │ │ title │ └──╼│ book_id │ │ published_at │ │ genre │ └──────────────┘ │ ISBN │ └──────────────┘ ``` ![ReferenceOneField](./img/reference-one-field.png) `` behaves like ``: it uses the current `record` (a book in this example) to build a filter for the book details with the foreign key (`book_id`). Then, it uses `dataProvider.getManyReference('book_details', { target: 'book_id', id: book.id })` to fetch the related details, and takes the first one. `` renders the [`recordRepresentation`](./Resource.md#recordrepresentation) of the related record. It also creates a `RecordContext` with the reference record, so you can use any component relying on this context (``, ``, etc.) as child. For the inverse relationships (the book linked to a book_detail), you can use a [``](./ReferenceField.md). **Tip**: To edit the records of a one-to-one relationship, use [the `` component](./ReferenceOneInput.md). ## Usage Here is how to render a field of the `book_details` resource inside a Show view for the `books` resource: ```jsx const BookShow = () => ( ); ``` **Tip**: As with ``, you can call `` as many times as you need in the same component, react-admin will only make one call to `dataProvider.getManyReference()` per reference. ## Props | Prop | Required | Type | Default | Description | | -------------- | -------- | ------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------- | | `reference` | Required | `string` | - | The name of the resource for the referenced records, e.g. 'book_details' | | `target` | Required | string | - | Target field carrying the relationship on the referenced resource, e.g. 'book_id' | | `children` | Optional | `ReactNode` | - | The Field element used to render the referenced record | | `render` | Optional | `(ReferenceFieldContext) => ReactNode` | - | A function that takes the `ReferenceFieldContext` and returns a React element | | `empty` | Optional | `ReactNode` | - | The text or element to display when the referenced record is empty | | `filter` | Optional | `Object` | `{}` | Used to filter referenced records | | `link` | Optional | `string | Function` | `edit` | Target of the link wrapping the rendered child. Set to `false` to disable the link. | | `offline` | Optional | `ReactNode` | - | The text or element to display when there is no network connectivity | | `queryOptions` | Optional | [`UseQueryOptions`](https://tanstack.com/query/v5/docs/framework/react/reference/useQuery) | `{}` | `react-query` client options | | `sort` | Optional | `{ field: String, order: 'ASC' or 'DESC' }` | `{ field: 'id', order: 'ASC' }` | Used to order referenced records | `` also accepts the [common field props](./Fields.md#common-field-props). ## `children` By default, `` renders the [`recordRepresentation`](./Resource.md#recordrepresentation) of the related record. If you pass a child component, it will be rendered instead, inside a `` of the fetched reference. This gives you entire freedom to display the related record. For instance, if you want to render both the genre and the ISBN for a book: ```jsx () ``` ## `empty` Use `empty` to customize the text displayed when the related record is empty. ```jsx () ``` `empty` also accepts a translation key. ```jsx () ``` `empty` also accepts a `ReactNode`. ```jsx } > () ``` ## `filter` You can also use `` in a one-to-many relationship. In that case, the first record will be displayed. The `filter` prop becomes super useful in that case, as it allows you to select the appropriate record to display. For instance, if a product has prices in many currencies, and you only want to render the price in euros, you can use: {% raw %} ```jsx ``` {% endraw %} ## `link` By default, `` links to the edition page of the related record. You can disable this behavior by setting the `link` prop to `false`. ```jsx ``` You can also set the `link` prop to a string, which will be used as the link type. It can be either `edit`, `show`, a route path, or a function returning a route path based on the given record. ```jsx `/custom/${record.id}`} > ``` ## `offline` When the user is offline, `` is smart enough to display the referenced record if it was previously fetched. However, if the referenced record has never been fetched before, `` displays an error message explaining that the app has lost network connectivity. You can customize this error message by passing a React element or a string to the `offline` prop: ```jsx No network, could not fetch data

} > ...
... ``` ## `queryOptions` `` uses `react-query` to fetch the related record. You can set [any of `useQuery` options](https://tanstack.com/query/v5/docs/framework/react/reference/useQuery) via the `queryOptions` prop. For instance, if you want to disable the refetch on window focus for this query, you can use: {% raw %} ```jsx ``` {% endraw %} ## `reference` The name of the resource to fetch for the related records. For instance, if you want to display the details of a given book, the `reference` name should be `book_details`: ```jsx ``` ## `render` Alternatively to `children`, you can pass a `render` prop to ``. It will receive the `ReferenceFieldContext` as its argument, and should return a React node. This allows to inline the render logic for the related record. ```tsx { if (isPending) { return

Loading...

; } if (error) { return

{error.toString()}

; } if (!referenceRecord) { return

No details found

; } return (
Genre
{referenceRecord.genre}
ISBN
{referenceRecord.ISBN}
); }} /> ``` ## `sort` You can also use `` in a one-to-many relationship. In that case, the first record will be displayed. This is where the `sort` prop comes in handy. It allows you to select the appropriate record to display. ![ReferenceOneField for one-to-many relationships](./img/reference-one-field-many.png) For instance, if you want to display the latest message in a discussion, you can use: {% raw %} ```jsx ``` {% endraw %} ## `target` The name of the field carrying the relationship on the referenced resource. For example, in the following schema, the relationship is carried by the `book_id` field: ``` ┌──────────────┐ ┌──────────────┐ │ books │ │ book_details │ │--------------│ │--------------│ │ id │───┐ │ id │ │ title │ └──╼│ book_id │ │ published_at │ │ genre │ └──────────────┘ │ ISBN │ └──────────────┘ ``` In that case, the `target` prop should be set to `book_id`: ```jsx ``` ## Displaying One Record In A Collection `` can also be used to display one record of a one-to-many relationship. Use `sort` and/or `filter` props to select the appropriate records to fetch. The first record will be displayed. For instance, to display only the latest review with a 5-star rating for a book: {% raw %} ```jsx const BookShow = () => ( ); ``` {% endraw %} ## Removing The Link By default, `` links to the edition page of the related record. You can disable this behavior by setting the `link` prop to `false`. ```jsx ```