Reference Field Reference
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(), 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 emits Target[].
Available from @strifeapp/strife 2.0.0 (@strifeapp/schema 0.22.0).
Example
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(). |
propertyName | string | No | Override the stored property name. |
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.
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. Nosizemeans no limit.multipleunset orfalse→ check the field in Studio first:- if editors can pick one document, set
size: 1; - if they can pick several, leave
sizeout. That happens when the template was last pushed with@strifeapp/strife1.7 or older, when an unsetmultiplemeant a list.
- if editors can pick one document, set
// 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 — the same editor, documented from the Strife Studio side.
fields.references()— 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.