Skip to content
Strife Docs

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

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

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

Options

OptionTypeRequiredDescription
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.
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.
TypeScript
// 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.