--- layout: default title: "The ReferenceOneFieldBase Component" storybook_path: ra-ui-materialui-fields-referenceonefieldbase--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. `` is a headless component, handling only the logic and relying on its `children` or `render` prop to render the UI. **Tip**: For a version based on MUI, see [``](/ReferenceOneField.html) **Tip**: For the inverse relationships (the book linked to a book_detail), you can use a [``](./ReferenceFieldBase.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 = () => ( ); const BookDetails = () => { const context = useReferenceFieldContext({ reference, target, }); if (context.isPending) { return

Loading...

; } if (context.error) { return

{context.error.toString()}

; } if (!context.referenceRecord) { return

No details found

; } return (

{context.referenceRecord.genre}

{context.referenceRecord.ISBN}

); } ``` **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\* | `Element` | - | React component to render the referenced record. | | `render` | Optional\* | `(ReferenceFieldContext) => Element` | - | A function that takes the `ReferenceFieldContext` and return 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). \* Either one of children or render is required. ## `children` You can pass any component of your own as children, to render the referenced record as you wish. You can access the list context using the `useReferenceFieldContext` hook. ```jsx const BookShow = () => ( ); const BookDetails = () => { const { isPending, error, referenceRecord } = useReferenceFieldContext({ reference, target, }); if (isPending) { return

Loading...

; } if (error) { return

{error.toString()}

; } if (!referenceRecord) { return

No details found

; } return (

{referenceRecord.genre}

{referenceRecord.ISBN}

); } ``` ## `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, `` populates the context with a `link` value that 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. {% raw %} ```jsx `/custom/${record.id}`} > ... ``` {% endraw %} ## `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 %} ## `render` Alternatively to children you can pass a `render` function prop to ``. The `render` function prop will receive the `ReferenceFieldContext` as its argument, allowing to inline the render logic. When receiving a `render` function prop the `` component will ignore the children property. ```jsx const BookShow = () => ( { if (isPending) { return

Loading...

; } if (error) { return

{error.toString()}

; } if (!referenceRecord) { return

No details found

; } return (

{referenceRecord.genre}

{referenceRecord.ISBN}

); }} /> ); ``` ## `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 ... ``` ## `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. ![ReferenceOneFieldBase 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 ... ```