Author
Dan Ribbens headshot
Dan Ribbens
Published On

Add Dynamic Descriptions to Customize the Editor

Author
Dan Ribbens headshot
Dan Ribbens
Published On
Add Dynamic Descriptions to Customize the Editor
Add Dynamic Descriptions to Customize the Editor
Descriptions can now be added to the admin UI on Fields, Globals and Collections

Descriptions are useful for giving contextual information to help content authors in the admin UI. They can be set with static text or made to give dynamic feedback to support a variety of use cases. You can configure descriptions on fields, collections and globals.

All the description properties support three types:

  • String
  • Function returning a string
  • React Component to be rendered

Let us explore some examples that represent real-world use cases.

Field Descriptions

On most field types the description will be displayed immediately after the input; Field types arrayblock, and group will show the description below the label. A collection configured with simple text field descriptions would look like the following:

1
{
2
// ... collapsed
3
fields: [
4
{
5
name: 'Order Details',
6
type: 'group',
7
admin: {
8
description: 'Customer can view this information'
9
},
10
fields: [
11
{
12
name: 'customerName',
13
type: 'text'
14
},
15
{
16
name: 'shipDate',
17
type: 'date',
18
admin: {
19
description: 'Date when package label was created',
20
width: '50%',
21
date: {
22
pickerAppearance: 'dayOnly'
23
}
24
}
25
},
26
// ... collapsed
27
]
28
}
29
]
30
}

Now anyone in the editing screen can understand exactly what is being represented.

Payload CMS Field Description Screenshot

Dynamic Field Descriptions

As useful as static text can be, the editing experience can be further enhanced using functions or full react components. The Payload docs has examples for both.

Using a function:

1
const labelField = {
2
name: 'label',
3
type: 'text',
4
maxLength: 20,
5
admin: {
6
description: ({ value }) => (
7
typeof value === 'string' ? `${20 - value.length} characters left` : ''
8
)
9
}
10
};

Or a react component:

1
const CharacterCount: React.FC = ({ value }) => (
2
<div>
3
Character count:
4
{' '}
5
{ value?.length || 0 }
6
</div>
7
);
8
9
const descriptionField = {
10
name: 'description',
11
type: 'textarea',
12
admin: {
13
description: CharacterCount,
14
},
15
};

Using these descriptions on your fields, the admin UI gives feedback as the user enters information.

Payload CMS Dynamic Field Descriptions Example

Collection Descriptions

They do not support passing in a value, but otherwise work the same as field descriptions. By using the description on a collection, the editor can gain knowledge about how the data is used.

Payload CMS Collection Description

A special case for collections with uploads is that the description also gets displayed on the modals for new file and selecting from existing.

Payload CMS New Media Upload Example

Global Descriptions

Descriptions can also be added to the edit screen on a Global beneath the label. Again, you can use this to explain extra details to the editor.

1
slug: 'navigation',
2
admin: {
3
description: 'Manage the website navbar and mobile menus',
4
},
5
// ...collapsed
6
}
Payload CMS Global Field Description Example

Building Further

Writing helpful descriptions for users can reduce the need for training or add that extra polish to impress a client. You can help users be more comfortable in a system by providing relevant explanations. Not only that, you might find your own descriptions useful when you come back in after being gone a long time.

Want to share an idea or ask the community? We love hearing from you in the Github discussions.