Code-based nature means you can build on top of it to power anything.
Resources
DocumentationExamplesTemplatesGitHubBlog
Community
RoadmapDiscordCommunity Help
Payload Cloud

Deploy your entire stack in one place with Payload Cloud.

LoginCloud Pricing
It’s time to take back your content infrastructure.
Schedule a Demo
Enterprise Features
SSOPublishing WorkflowsVisual EditorStatic A/B testingAI features
Customer Stories
MicrosoftBlue OriginHello BelloMythical SocietyTekton
Featured Customer Story

Microsoft chose Payload to tell the world about AI.

Read the case study
New projectLogin
New projectLogin
Author
Headshot of a white male adult wearing glasses and a black t-shirt, in front of a black backdrop.
Jarrod Flesch
@jarrodmflesch
Published On

Managing Array and Block Rows with Ease

Author
Headshot of a white male adult wearing glasses and a black t-shirt, in front of a black backdrop.
Jarrod Flesch
@jarrodmflesch
Published On
Easily move your rows around with custom components
Easily move your rows around with custom components
Managing form state within arrays and blocks has been a bit cumbersome. We just shipped new ways to make it easier. Payload is built with extensibility in mind. In this post we will show how easy it is to add, replace and remove rows within array and block fields.

In this example collection we have two fields, an array field and a custom ui field.

1
const ExampleCollection: CollectionConfig = {
2
slug: "example-collection",
3
fields: [
4
{
5
name: "arrayField",
6
type: "array",
7
fields: [
8
{
9
name: "textField",
10
type: "text",
11
},
12
],
13
},
14
{
15
type: "ui",
16
name: "customArrayManager",
17
admin: {
18
components: {
19
Field: CustomArrayManager,
20
},
21
},
22
},
23
],
24
};

The ui field’s custom component will allow us to perform actions on the array field. Here is a snippet of what this could look like:

1
import * as React from "react";
2
import { useForm } from "payload/components/forms";
3
4
export const CustomArrayManager: React.FC = () => {
5
const { addFieldRow, replaceFieldRow, removeFieldRow } = useForm();
6
7
return (
8
<div style={{ display: "flex", gap: "10px" }}>
9
<button
10
onClick={() => {
11
addFieldRow({
12
path: "arrayField",
13
rowIndex: 0,
14
data: {
15
textField: "text",
16
},
17
});
18
}}
19
type="button"
20
>
21
Add Row
22
</button>
23
24
<button
25
type="button"
26
onClick={() => {
27
replaceFieldRow({
28
path: "arrayField",
29
rowIndex: 0,
30
data: {
31
textField: "updated text",
32
},
33
});
34
}}
35
>
36
Replace Row
37
</button>
38
39
<button
40
type="button"
41
onClick={() => {
42
removeFieldRow({
43
path: "arrayField",
44
rowIndex: 0,
45
});
46
}}
47
>
48
Remove Row
49
</button>
50
</div>
51
);
52
};

To interact with the form data, we now expose a couple helper functions through Payloads useForm hook.

Managing Array rows

addFieldRow

You can use this when you want to programmatically add a new row to an array field:

1
const { addFieldRow } = useForm();
2
3
return (
4
<button
5
onClick={() => {
6
addFieldRow({
7
path: "arrayField",
8
rowIndex: 0,
9
data: {
10
textField: "text",
11
},
12
});
13
}}
14
type="button"
15
>
16
Add Row
17
</button>
18
)

Arguments:

  • path: the path of the field that you want to target. If this was a nested field, you would need to pass the whole path, i.e. outerArrayField.0.innerArrayField
  • rowIndex: (optional) the row index used to insert the data at
  • data: the new row data
replaceFieldRow

You can use this when you want to programmatically replace a row within an array field:

1
const { replaceFieldRow } = useForm();
2
3
return (
4
<button
5
onClick={() => {
6
replaceFieldRow({
7
path: "arrayField",
8
rowIndex: 0,
9
data: {
10
textField: "updated text",
11
},
12
});
13
}}
14
type="button"
15
>
16
Replace Row
17
</button>
18
)

Arguments:

  • path: the path of the field that you want to target. If this was a nested field, you would need to pass the whole path, i.e. outerArrayField.0.innerArrayField
  • rowIndex: the index of the row that you want to replace
  • data: the replacement row data
removeFieldRow

To be used when you want to programmatically remove a row from an array field:

1
const { removeFieldRow } = useForm();
2
3
return (
4
<button
5
onClick={() => {
6
removeFieldRow({
7
path: "arrayField",
8
rowIndex: 0,
9
});
10
}}
11
type="button"
12
>
13
Remove Row
14
</button>
15
)

Arguments:

  • path: the path of the field that you want to target. If this was a nested field, you would need to pass the whole path, i.e. outerArrayField.0.innerArrayField
  • rowIndex: the index of the row that you want to remove

Managing Block rows

The implementation for blocks is identical to arrays, just be sure to pass blockType in the data object. Here is another simple collection example we have a blocks field and our custom ui field:

1
const ExampleCollection: CollectionConfig = {
2
slug: "example-collection",
3
fields: [
4
{
5
name: "blocksField",
6
type: "blocks",
7
blocks: [
8
{
9
slug: "textBlock",
10
fields: [
11
{
12
name: "textField",
13
type: "text",
14
},
15
]
16
},
17
],
18
},
19
{
20
type: "ui",
21
name: "customArrayManager",
22
admin: {
23
components: {
24
Field: CustomArrayManager,
25
},
26
},
27
},
28
],
29
};
addFieldRow

You can use this just like in the array example, just pass the blockType along with the row data:

1
const { addFieldRow } = useForm();
2
3
return (
4
<button
5
onClick={() => {
6
addFieldRow({
7
path: "blocks",
8
rowIndex: 0,
9
data: {
10
blockType: "textBlock",
11
textField: "block text",
12
},
13
});
14
}}
15
type="button"
16
>
17
Add Block
18
</button>
19
)
replaceFieldRow

You can use this just like in the array example, just pass the blockType along with the row data:

1
const { replaceFieldRow } = useForm();
2
3
return (
4
<button
5
onClick={() => {
6
replaceFieldRow({
7
path: "blocks",
8
rowIndex: 0,
9
data: {
10
blockType: "textBlock",
11
textField: "updated block text",
12
},
13
});
14
}}
15
type="button"
16
>
17
Replace Block
18
</button>
19
)
removeFieldRow

This is the exact same for array and block fields.

Recap

This is a bit of a technical update, but I think this feature warrants it because of the potential power it holds. With this you can easily manage blocks and arrays to fit your custom needs. You could create a custom component where the user selects a block type from a dropdown, writes a prompt and then you programmatically insert generated data that fits the block type into the form.

There are a lot of possibilities when extending Payload, the goal is to make it easier.

Learn more