docs

⌘K
  2. Home
  4. Docs
  6. docs
  8. Widgets
  10. Relation

Relation

  • Name: relation
  • UI: Text input with search result dropdown
  • Data type: Data type of the value pulled from the related collection item

The relation widget allows you to reference items from another collection. It provides a search input with a list of entries from the collection you are referencing, and the list automatically updates with matched entries based on what you have typed.

Widget Options

For common options, see Common widget options.

Name

Type

Default

Description

collection

string

Name of the referenced collection

value_field

string

Name of the field from the referenced collection whose value will be stored for the relation. For nested fields, separate each subfield with a . (e.g. name.first). For list fields use a wildcard * to target all list items (e.g. categories.*)

search_fields

list of strings

List of one or more names of fields in the referenced collection to search for the typed value. Syntax to reference nested fields is similar to that of value_field

default

Any widget data type

''

Optional. The default value for the field. Accepts any widget data type

file

string

Optional. Allows referencing a specific file when the referenced collection is a files collection

display_fields

list of strings

Optional. list of one or more names of fields in the referenced collection that will render in the autocomplete menu of the control. Defaults to value_field. Syntax to reference nested fields is similar to that of value_field

multiple

boolean

false

Optional. Allow multiple values to be selected

min

number

Optional. Minimum number of items. Ignored if multiple is false

max

number

Optional. Maximum number of items. Ignored if multiple is false

options_length

number

20

Optional. Number of options presented to user

Examples

Referencing A Folder Collection

Assuming a separate “authors” collection with “name” and “twitterHandle” fields with subfields “first” and “last” for the “name” field.

name: author
label: Post Author
widget: relation
collection: authors
search_fields: ['name.first', 'twitterHandle']
value_field: name.first
display_fields: ['twitterHandle', 'followerCount']
name: 'author',
label: 'Post Author',
widget: 'relation',
collection: 'authors',
search_fields: ['name.first', 'twitterHandle'],
value_field: 'name.first',
display_fields: ['twitterHandle', 'followerCount'],

The generated UI input will search the authors collection by name and twitterHandle, and display each author’s handle and follower count. On selection, the author’s name is saved for the field.

String Template

Assuming a separate “authors” collection with “name” and “twitterHandle” fields with subfields “first” and “last” for the “name” field.

name: author
label: Post Author
widget: relation
collection: authors
search_fields: ['name.first']
value_field: '{{slug}}'
display_fields: ['{{twitterHandle}} - {{followerCount}}']
name: 'author',
label: 'Post Author',
widget: 'relation',
collection: 'authors',
search_fields: ['name.first'],
value_field: '{{slug}}',
display_fields: ['{{twitterHandle}} - {{followerCount}}'],

The generated UI input will search the authors collection by name, and display each author’s handle and follower count. On selection, the author entry slug is saved for the field.

Referencing A File Collection List Field

Assuming a separate “relation_files” collection with a file named “cities” with a list field “cities” with subfields “name” and “id”.

name: city
label: City
widget: relation
collection: relation_files
file: cities
search_fields: ['cities.*.name']
display_fields: ['cities.*.name']
value_field: 'cities.*.id'
name: 'city',
label: 'City',
widget: 'relation',
collection: 'relation_files',
file: 'cities',
search_fields: ['cities.*.name'],
display_fields: ['cities.*.name'],
value_field: 'cities.*.id',

The generated UI input will search the cities file by city name, and display each city’s name. On selection, the city id is saved for the field.