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
      ]
    }
  ]
}

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

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` : ''
    )
  }
};

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,
    },
  };

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

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.

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

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
}

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.