---
title: Ref field
description: Display records that the current record points to.
---

A Ref field represents a forward relation, such as an order that points to a
customer. The declaration identifies the target resource and the field that
displays each related record.

## API

```ts
fields.ref(
  name,
  () => resource,
  options: RefFieldOptions & { display: string | FieldBuilder }
)
```

| Option         | Input                   | Result                                    |
| -------------- | ----------------------- | ----------------------------------------- |
| `display`      | `string`, field builder | Displays through a target resource field. |
| `label`        | `string`                | Sets the text shown for the field.        |
| `description`  | `string`                | Adds supporting text for the label.       |
| `inputVariant` | lookup input variant    | Selects a related value through a lookup. |
| `cardinality`  | `one`, `many`           | Selects one related value or an array.    |

`configure(options)` returns a configured clone. `clone()` returns an
independent copy with the same target declaration and options. `configure` can replace the display field. The target resource stays fixed.

The target resource function is a type-safe authoring reference. The protocol
sends the complete display field.

## Basic Ref field

The related record is read through its declared display field.

<BacklitExample path="fields/ref/basic" view="detail" />

## Related record

Pass the related record. The display field reads and converts its value.

<BacklitExample path="fields/ref/record" view="detail" />

## Description

<BacklitExample path="fields/ref/description" view="detail" />

## Display link

Configure the display field with `link`. The related record must contain every
value that its field and link args callback use.

<BacklitExample path="fields/ref/display_link" view="detail" />

## Lookup input variant

Use a lookup target as the input variant. Its `value` field
defines the value type written by the input.

<BacklitExample path="fields/ref/input_lookup" view="detail" />

## Cardinality

Use `one` for one related record and `many` for an array of related records.

<BacklitExample path="fields/ref/cardinality" view="detail" />

## Clone

Use `configure` when one view must change a role variant without changing the
shared field.

<BacklitExample path="fields/ref/clone" view="detail" />

## All options

A Ref field can use display and input targets, metadata, and many cardinality
together.

<BacklitExample path="fields/ref/all_options" view="detail" />