Add Dynamic Descriptions to Customize the Payload CMS Admin UI
Tags: react, node, programming, javascript
Published: 2021-08-03 02:22:19

If you are using Payload CMS, you can now add descriptions 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 `array`, `block`, and `group` will show the description below the label. A collection configured with simple text field descriptions would look like the following:
```js
{
  // ... collapsed
  fields: [
    {
      name: 'Order Details',
      type: 'group',
      admin: {
        description: 'Customer can view this information'
      },
      fields: [
        {
          name: 'customerName',
          type: 'text'
        },
        {
          name: 'shipDate',
          type: 'date',
          admin: {
            description: 'Date when package label was created',
            width: '50%',
            date: {
              pickerAppearance: 'dayOnly'
            }
          }
        },
        // ... collapsed
      ]
    }
  ]
}
```
Now anyone in the editing screen can understand exactly what is being represented.
![Field Descriptions](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3y7e06spt38dbubi201g.png)

### 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](https://payloadcms.com/docs/fields/overview#description) has examples for both.

Using a function:
```ts
const labelField = {
  name: 'label',
  type: 'text',
  maxLength: 20,
  admin: {
    description: ({ value }) => (
      typeof value === 'string' ? `${20 - value.length} characters left` : ''
    )
  }
};
```

Or a react component:
```tsx
const CharacterCount: React.FC = ({ value }) => (
  <div>
    Character count:
    {' '}
    { value?.length || 0 }
  </div>
);

const descriptionField = {
    name: 'description',
    type: 'textarea',
    admin: {
      description: CharacterCount,
    },
  };
```

Using these descriptions on your fields, the admin UI gives feedback as the user enters information.
![Dynamic field descriptions](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/d6mnnaq6ry1fj6ae9ag2.png)

## 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.
![Collection description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/eijibg9rxdfki9kjo37y.png)

A special case for collections with uploads is that the description also gets displayed on the modals for new file and selecting from existing.
![Upload description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/unadoke6knxh642frks2.png)

## 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.

```
export default {
  slug: 'navigation',
  admin: {
    description: 'Manage the website navbar and mobile menus',
  },
  // ...collapsed
}
```
![Global description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xzt64bc3cztqkcy46q68.png)

## 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](https://github.com/payloadcms/payload/discussions).