ReferenceOneField

Displays a related record from a one-to-one relationship by fetching the record whose target field matches the current record's id (or source).

Installation

pnpm dlx shadcn@latest add @shadmin/reference-one-field

The children are rendered inside a RecordContext populated with the referenced record, so any field component can be used inside.

Usage

import { ReferenceOneField, TextField } from "@/components/admin";
 
<ReferenceOneField reference="bios" target="author_id">
  <TextField source="body" />
</ReferenceOneField>;

Props

Prop	Required	Type	Default	Description
`reference`	Required	`string`	-	Name of the related resource
`target`	Required	`string`	-	Foreign key on the related record
`source`	Optional	`string`	`"id"`	Field on the current record to match against `target`
`sort`	Optional	`SortPayload`	-	Sort applied when fetching the related record
`filter`	Optional	`object`	-	Filter applied when fetching the related record
`link`	Optional	`LinkToType`	-	Link the rendered field to the related record
`empty`	Optional	`ReactNode`	-	Rendered when no record is found
`loading`	Optional	`ReactNode`	-	Rendered while the request is pending
`offline`	Optional	`ReactNode`	`<Offline />`	Element rendered when the network is offline
`error`	Optional	`ReactNode`	-	Rendered when the request fails
`record`	Optional	`object`	Record from context	Explicit current record
`queryOptions`	Optional	`UseQueryOptions`	-	Extra options forwarded to TanStack Query
`render`	Optional	`(state) => ReactNode`	-	Custom render function. Receives the controller result
`children`	Optional	`ReactNode`	-	Field components to render with the referenced record in context

`reference`

Name of the resource holding the related record. Must match a <Resource> declared in <Admin>.

<ReferenceOneField reference="bios" target="author_id">
  <TextField source="body" />
</ReferenceOneField>

`target`

The field on the related record that points back to the current record. ReferenceOneField fetches the first record where target == currentRecord[source].

`link`

Wrap the rendered field in a <Link> to the related record. Accepts "show", "edit", false, a path, or a function returning a path.

<ReferenceOneField reference="bios" target="author_id" link="show">
  <TextField source="body" />
</ReferenceOneField>

`offline`

Element rendered when the network is offline and the reference data is unavailable. Defaults to the inherited offline component from ra-core.

<ReferenceOneField
  reference="bios"
  target="author_id"
  offline={
    <span className="text-muted-foreground italic">
      Offline — biography unavailable
    </span>
  }
>
  <TextField source="body" />
</ReferenceOneField>

`render`

Provide a render function instead of children to access the controller state directly.

<ReferenceOneField
  reference="bios"
  target="author_id"
  render={({ referenceRecord, isPending }) =>
    isPending ? "Loading..." : referenceRecord?.body
  }
/>