Reference

The reference type creates a relationship between documents. It renders a searchable dropdown that lets users pick from existing documents of the specified type.

Definition

import type { ReferenceField } from '@aphexcms/cms-core';

{
  name: 'author',
  type: 'reference',
  title: 'Author',
  to: [{ type: 'person' }],
  validation: (Rule) => Rule.required()
}

Properties

Property	Type	Required	Description
`name`	`string`	Yes	Field identifier.
`type`	`'reference'`	Yes	Must be `'reference'`.
`title`	`string`	Yes	Label shown in the admin UI.
`description`	`string`	No	Help text shown below the label.
`to`	`Array<{ type: string }>`	Yes	Document types this field can reference. Currently only the first type in the array is used by the component.
`initialValue`	`any \| () => any \| Promise<any>`	No	Default value.
`validation`	`(Rule) => Rule`	No	Validation rules.

Examples

Single type reference

{
  name: 'category',
  type: 'reference',
  title: 'Category',
  to: [{ type: 'category' }],
  validation: (Rule) => Rule.required()
}

Author reference in a blog post

const post: SchemaType = {
	type: 'document',
	name: 'post',
	title: 'Blog Post',
	fields: [
		{ name: 'title', type: 'string', title: 'Title' },
		{
			name: 'author',
			type: 'reference',
			title: 'Author',
			to: [{ type: 'author' }],
			validation: (Rule) => Rule.required()
		},
		{ name: 'body', type: 'text', title: 'Body' }
	]
};

UI Features

When no reference is selected:

Searchable dropdown showing documents of the target type (first 10 results)
"Create new" button to create a referenced document on the fly

When a reference is selected:

Shows the referenced document's title, type, and status (draft/published)
Button to open the referenced document in the editor
Button to clear the selection

Stored Data

References store the ID of the referenced document as a string:

{
	author: 'document-id-123';
}

Validation

Available rules: required(), custom(fn), error(msg), warning(msg), info(msg)

Reference

On this page