DEV Community

Cover image for Add Dynamic Descriptions to Customize the Payload CMS Admin UI
Dan Ribbens for Payload CMS

Posted on • Originally published at payloadcms.com

Add Dynamic Descriptions to Customize the Payload CMS Admin UI

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:

{
  // ... 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
      ]
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

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

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:

const labelField = {
  name: 'label',
  type: 'text',
  maxLength: 20,
  admin: {
    description: ({ value }) => (
      typeof value === 'string' ? `${20 - value.length} characters left` : ''
    )
  }
};
Enter fullscreen mode Exit fullscreen mode

Or a react component:

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

const descriptionField = {
    name: 'description',
    type: 'textarea',
    admin: {
      description: CharacterCount,
    },
  };
Enter fullscreen mode Exit fullscreen mode

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

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

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

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
}
Enter fullscreen mode Exit fullscreen mode

Global description

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.

Discussion (1)

Collapse
joephuz profile image
joephuz

great example, thank you...