SchemaReferenceField

Displays a foreign key as a chip carrying the related record's representation.

The chip links to the related record by default. Point targetSource at a field of the related record when you want to show one of its values instead of its representation.

Example

<SchemaReferenceField source="category_id" reference="eshop/category" />;

{
  /* Show the category name instead of its representation */
}
<SchemaReferenceField
  source="category_id"
  reference="eshop/category"
  targetSource="name"
/>;

Props

Name	Type	Default	Description
source (required)	string	—	Field on the record holding the foreign key
reference	string	resource from context	Target resource, e.g. "eshop/category"
targetSource	string	—	Field of the related record to render instead of its representation
label	string | ReactElement | false	label from the schema	false hides the label
emptyText	string	—	Text shown when the reference is empty
options.relation	RelationFieldOptions	from the schema	See the table below

options.relation

Option	Type	Default	Description
showLink	boolean	true	Whether the chip is clickable
linkMode	'dialog' | 'redirect' | 'sidepanel'	the target view's own mode	'dialog' opens the related record in a dialog instead of navigating away. It is a request, not a verdict: it is resolved against the target view's own mode, the surface the field sits on and whether a side panel is available — 'sidepanel' with no panel to dock into opens a dialog, and inside a dialog a 'redirect' link closes it and navigates
dialogWidth	string	"md"	linkMode: 'dialog' only — MUI breakpoint ("sm"…"xl") or any CSS width ("800px")
preserveOrder	boolean	true unless sort is set	Array references only — keeps the order stored on the record
parent	string	—	Array references only — field forming the tree in format: "tree-relation"

showEditButton and showCreateButton also live under options.relation, but they are read by SchemaReferenceInput, not by this field.

In a list the chip is truncated to the column width so a long representation cannot widen the column.

caution

When the related resource's schema cannot be loaded, the component degrades to plain text showing the raw key. That usually means the referenced resource is missing from the service schema, or the user has no permission to read it.

Schema mapping

format: "relation" (or "tree-relation") with a reference:

{
  "name": "category_id",
  "type": "integer",
  "format": "relation",
  "reference": "eshop/category",
  "options": { "relation": { "linkMode": "dialog", "dialogWidth": "md" } }
}

An array of references (items.reference) renders as a row of chips — SchemaReferenceArrayField.

Python

A belongs_to-style relation on the model emits the reference automatically; a Field descriptor with RelationFieldOptions carries the display options:

from habarico import ModelAdmin
from habarico.schema import Field
from habarico.schema.fields import RelationOptions


class ProductAdmin(ModelAdmin):
    model = Product
    fields = [
        "id",
        "name",
        Field(name="category", relation=RelationOptions(link_mode="dialog")),
    ]

Ruby

Building one by hand

SchemaReferenceField is a schema wrapper around ReferenceField, which is exported too and reads no schema at all: it resolves the reference, adds the active locale to the query so the related record comes back translated, and renders its child inside the referenced record's context.

<ReferenceField reference="eshop/category" source="category_id">
  <SchemaRecordRepresentationChip link linkMode="dialog" />
</ReferenceField>

Its recordLinkProps fills the default chip when you pass no child; a schema-aware chip has to arrive as a child instead, because the resource it reads is the referenced one and exists only inside the field. ReferenceArrayField is the same thing for arrays.

See also

• SchemaReferenceInput — the form counterpart
• SchemaReferenceArrayField — an array of foreign keys
• RecordRepresentationChip — the chip this field renders
• useRecordLink — the link behind the chip
• Cross-service references — referencing a resource served by another backend
• FieldSchema — the full RelationFieldOptions type