---
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 │
└──────────────┘
```

`` 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.

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
```