Relationship Field

The Relationship field is one of the most powerful fields Payload features. It provides for the ability to easily relate documents together.

Example uses:

To add Product documents to an Order document
To allow for an Order to feature a placedBy relationship to either an Organization or User collection
To assign Category documents to Post documents

Config

Option	Description
`name` *	To be used as the property name when stored and retrieved from the database.
*`relationTo`** *	Provide one or many collection `slug`s to be able to assign relationships to.
`hasMany`	Boolean when, if set to `true`, allows this field to have many relations instead of only one.
`label`	Used as a field label in the Admin panel and to name the generated GraphQL type.
`unique`	Enforce that each entry in the Collection has a unique value for this field.
`validate`	Provide a custom validation function that will be executed on both the Admin panel and the backend. More
`index`	Build a MongoDB index for this field to produce faster queries. Set this field to `true` if your users will perform queries on this field's data often.
`saveToJWT`	If this field is top-level and nested in a config supporting Authentication, include its data in the user JWT.
`hooks`	Provide field-based hooks to control logic for this field. More
`access`	Provide field-based access control to denote what users can see and do with this field's data. More
`hidden`	Restrict this field's visibility from all APIs entirely. Will still be saved to the database, but will not appear in any API or the Admin panel.
`defaultValue`	Provide data to be used for this field's default value.
`localized`	Enable localization for this field. Requires localization to be enabled in the Base config.
`required`	Require this field to have a value.
`admin`	Admin-specific configuration. See the default field admin config for more details.

* An asterisk denotes that a property is required.

Tip:
The Depth parameter can be used to automatically populate related documents that are returned by the API.

Example

collections/ExampleCollection.js

{
  slug: 'example-collection',
  fields: [
    {
      name: 'placedBy', // required
      type: 'relationship', // required
      relationTo: ['organizations', 'users'], // required
      label: 'Placed By',
      hasMany: false,
      required: true,
    }
  ]
}

Relationship Field

Config

Example

Rich Text Field

On this page