Add Dynamic Row Labels for Array Fields in Payload CMS

Labels for Array Fields in Payload CMS

I know many of you have been searching for a way to set custom/dynamic labels for array rows in Payload CMS. I was in the same boat — scrolling through forums and docs — until I found the solution. So, I created this guide (by referring to the official Payload docs here) to make it super easy for everyone to understand.

Why You Need Dynamic Row Labels

By default, Payload shows your array rows as Row 1, Row 2, etc.

That’s fine for small arrays, but when you have a lot of rows, it’s hard to know which one is which without opening them.

With dynamic labels, each row can display something meaningful — for example, a “Link Text” value for navigation links. This makes editing much easier for you or your clients.

Step 1: Set Up Your Array Field

In your collection or global config, create an array field and point its RowLabel to a custom component.

{
  name: "headerLinks",
  label: "Header Links",
  type: "array",
  admin: {
    components: {
      RowLabel: "@/components/payload/arrayRowLabel",
    },
  },
  fields: [
    {
      type: "row",
      fields: [
        { name: "text", type: "text", label: "Link Text", required: true },
        { name: "url", type: "text", label: "Link URL", required: true },
        { name: "newTab", type: "checkbox", label: "Open in New Tab" },
      ],
    },
  ],
}

Step 2: Create the Custom Row Label Component

Create arrayRowLabel.tsx in your components folder:

"use client";
import { useRowLabel } from "@payloadcms/ui";

export const ArrayRowLabel = () => {
  const { data, rowNumber } = useRowLabel<{ text?: string }>();

  const customLabel = data.text || `Link ${String(rowNumber).padStart(2, "0")}`;

  return {customLabel};
};

export default ArrayRowLabel;

Here’s what’s happening:

  • useRowLabel gives you the row’s data and position.
  • If the text field exists, we use it as the label.
  • If not, we show a fallback like “Link 01”, “Link 02”, etc.

Step 3: See the Result in the Admin

Now when you open your Payload admin panel, your array rows will have meaningful labels instead of generic “Row 1” names.
This makes it much easier to find what you’re looking for.

Conclusion

It’s a small change, but it makes a big difference in the content editing experience.
No more guessing which row is which — now you can label them based on your actual data. I hope this saves you time and frustration. If you want to dive deeper, check out the official Payload docs on RowLabel.


Thank You!