Organize PayloadCMS Like a Pro: Tabs, Rows, Groups, and Collapsible Fields
Learn all about Payload CMS presentational fields
14:33 video • ~6 min readPayload CMS
Support:Subscribe
In this guide, I'll go over presentational fields in Payload CMS.
Learn all about Payload CMS presentational fields
In this guide, I'll go over presentational fields in Payload CMS.
The main fields we covered in the last guide can be organized in your PayloadCMS instance by using the following fields that I’ve called layout fields. Payload calls a few of these presentational fields. This includes the row, tabs, collapsible, and group fields.
Presentational fields do not store data in your database, but they give you a way to organize and present the main fields we discussed in the previous guide. Let’s start with tabs.
Tabs are useful when you want to keep different sections of your site in separate large groups. These can either be representation (do not store data in the database) or a data field (do store data in the database). When you name a tab, it is automatically included as a data field.
Since Tabs can be either a representational or data field, “name” is optional. You do not need to include it if you want the Tabs field to only organize your backend. This is useful for the times you want to organize how you see the data in your admin panel, but if you don’t want to add an extra layer when rendering the information on your frontend.
This means the only required fields needed to initialize your Tabs is the type field and two new options: fields and label. Fields should be an array of all the fields you would like to include in your tab. Label should be a string that labels your Tabs so you can know which Tab you want to store which fields.
A great use case for tabs is when you want to have an easy way to store large sections of your collection in different areas. For example, if you have a Hero section, you can have one tab for the hero section, another tab for the general content of your page, and then a third tab that handles all of the SEO information for the page. This flexibility means you don’t need to scroll through lots of data to get to specific parts of your admin UI. You can just click on the SEO tab to get to your SEO information, and then click back over to your Hero tab and make edits there.
The next field we’ll talk about is the row field. The row field is called a presentational field by the PayloadCMS team. This field allows you to align fields horizontally. By default, fields take up 100% of their space, but you can use rows to change that.
Since Row is presentational and does not store data, you don’t need to give it a name. Instead, you only need to provide the type option and the fields option. The fields option is an array of fields that you would like to organize in the row.
Using the Row field by itself will still let all the fields take up 100% of the available space. To get the full benefit of the Row field, you will want to provide an admin.width to the fields inside the row. This field should be a string representation of a percentage value in order to work properly. For example, if you want a field to take up 50% of the container width, you will need to write admin.width: {‘50%’}.
One thing to call out here on Row fields: you cannot use a description with Row fields. readOnly and hidden are also excluded from the Row field’s admin configuration, so you will not be able to hide your row field or prevent it from being edited.
The collapsible field is presentational-only and is just used to organize the Admin Panel. This allows you to group fields together into an organized, collapsible box that can be expanded or collapsed without adding an extra layer to be rendered on the frontend.
Since the collapsible field is presentational, you do not need a name field. All you need is the type, fields, and label options. The label option allows you to have some flexibility as well. You can provide a string, a component, or a function using ({data, path}) as arguments. This function will allow you to programmatically set the label of the collapsible field based on data from within the field.
You also have the ability to set the initial state of the collapsible field. You can set admin.initCollapsed to true in order to force the collapsible field into its collapsed state on page load.
Array fields are data fields, not presentational. These fields will help you organize your Admin Panel, but they will also store the values of your fields as an array of values in your database to be looped through on the frontend.
You need to include the type, name, and fields options when initializing an Array field, and the fields option needs to be an array of fields you would like to have repeated as you add a new row to your Array.
Similar to the collapsible field, you can set the initial collapsed state by setting admin.initCollapsed. You can also set admin.isSortable to true to allow you to sort the array fields’ children by dragging and dropping the fields in the order you want them to be in. You also have the option to set custom Row Labels using a custom component, but we will cover that in a later guide.
You may also set the maximum and minimum number of rows you want this field to have. This isn’t defined by default, so if you don’t have minRows or maxRows set, you could have 0 rows or 100s of rows. When setting these, be sure to have the final design in mind so you know how many rows are required to complete the project.
Group names are now optional.
Like Array fields, Group fields are data fields, not presentational. So, while they do allow you to organize your fields in a nice layout, Group fields will save data to the database. The way this works is that the Group name becomes a common property name for all of its children fields. For example, if you have a Group field named “group” and you have a field nested within your “group” field and its name is “child,” that field’s value will be saved as group.<child> in your database.
The name, type, and fields options are required for a Groups field with the fields option being an array of fields you would like to group.
Be sure to understand how groups will be used on the frontend. It can be confusing if you have data in a group field that won’t be used in the same portion of your frontend as it is in the backend. I’ve run into issues where I’ve created a group called “sidebar” to group some fields into the sidebar of my admin panel and then had to include .sidebar on my frontend, which doesn’t make a whole lot of sense.
Each of these fields can help you organize and group your Payload CMS admin panel in ways that make sense and streamline your work. Beyond nesting fields together, you can then use these fields to build blocks of fields to then be used throughout the rest of your project. There are more fields, and one we will come back to in a later guide is Blocks.