> From the [Strife developer docs](https://strife.app/docs/reference/field-reference/fields.related). Every page is listed in [llms.txt](https://strife.app/docs/llms.txt).

# fields.related()

One-way links to other Strife documents, picked in Studio and scoped by target type. Replaces fields.reference(). Not localizable.

One-way links to other Strife documents. Maps to editor `{ name: 'str-related', type: 'related' }`, the same editor as the deprecated [`fields.reference()`](https://strife.app/docs/reference/field-reference/fields.reference.md), which `fields.related()` replaces. Not localizable: the content index never treats relations as per-locale values.

Editors pick the documents in Strife Studio. The new interface shows them as chips; the classic interface as a searchable list.

Stored as an array of document ids, and `Infer<>` gives `string[]`. (The classic interface saves `{ id, displayName }` copies instead; Strife reads both.) At **read** time the content index replaces each entry with the full target document, so [`strife typegen`](https://strife.app/docs/reference/cli/typegen.md) emits `Target[]`.

Available from `@strifeapp/strife` 2.0.0 (`@strifeapp/schema` 0.22.0).

## Example

```ts
fields.related({
  label: 'Author',
  to: 'author',
  size: 1,
})

fields.related({
  label: 'Related articles',
  to: ['article', 'video-post'],
})
```

## Options

| Option         | Type                          | Required | Description                                                                                                                                                                                                  |
| -------------- | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `label`        | `string`                      | Yes      | Label shown to editors in Strife Studio.                                                                                                                                                                     |
| `to`           | `string \| readonly string[]` | Yes      | The `defineType` name(s) the field may link to. Resolves to the editor's `allowedCollections` via the default collection rule (`toPlural(toPascalCase(name))`) and drives the generated read type (`Target[]`). |
| `size`         | `number \| null`              | No       | Maximum number of linked documents (wire `attributes.size`). `1` makes it a single pick. Leave it out for no limit. The same option as on [`fields.references()`](https://strife.app/docs/reference/field-reference/fields.references.md).                     |
| `propertyName` | `string`                      | No       | Override the stored property name.                                                                                                                                                                           |

> [!WARNING]
> **Don't name the field `related`.** Every document already has a built-in `related` property: a two-way relation Strife keeps on both documents. A top-level field stored as `related` is that property, so the new interface shows it as the document's Related row and ignores the field's `to`, `size` and label. `strife push` warns about it. Use a name of its own, such as `relatedArticles`. Inside a chapter, `related` is an ordinary field.

> [!NOTE]
> If a target `defineType` overrides its own `collection`, the derived `allowedCollections` (which only scopes the Studio picker) won't match it, and nothing warns about it. The generated read type is correct either way.

## Switching from `fields.reference()`

Keep the key (or `propertyName`) and `to`. Then:

* `multiple: true` → leave it out. No `size` means no limit.
* `multiple` unset or `false` → check the field in Studio first:
  * if editors can pick one document, set `size: 1`;
  * if they can pick several, leave `size` out. That happens when the template was last pushed with `@strifeapp/strife` 1.7 or older, when an unset `multiple` meant a list.

```ts
// Before
author: fields.reference({ label: 'Author', to: 'author' }),
partners: fields.reference({ label: 'Partners', to: 'company', multiple: true }),

// After
author: fields.related({ label: 'Author', to: 'author', size: 1 }),
partners: fields.related({ label: 'Partners', to: 'company' }),
```

Values already saved in the field keep working: it is the same editor. From `@strifeapp/cli` 0.1.20, `strife push` and `strife typegen validate` refuse `fields.reference()` when the project's `@strifeapp/strife` is 2.0.0 or later, and warn with an older one. Either way, the message names the change for each field, but it can't see the stored template: for a field that is still a list from 1.7 or older, it says `size: 1`. Studio decides, not the message.

## Output type

Write shape: `string[]`, the document ids. Generated read shape (via `strife typegen`): `Target[]`, the fully projected target document(s).

## See also

* [Related](https://strife.app/docs/reference/fields/related.md) — the same editor, documented from the Strife Studio side.
* [`fields.references()`](https://strife.app/docs/reference/field-reference/fields.references.md) — a different editor (`str-references`), for content the document owns: an ordered list scoped by template name (`allow`), which a publish follows through every level.
