Intro
Welcome to part 2 of building custom form fields. If you haven't completed part 1 I recommend going through that first before diving into this, but I've supplied all the code required to get this working. You can also check out a working repo from my Github.
Now let's create an array field for our form. The example is going to be a contact form to submit an issue. But what if they had multiple issues to submit? Let's improve the UX by allowing the customer to submit up to 4 issues at a time in a single (dynamic) form submission.
Create a Payload Website
To follow along you can load up a brand new payload website template.
pnpm dlx create-payload-app
Follow the prompts to create a website project. I use mongodb because I find it the simplest when making changes to the schema. Log into the admin panel, seed the dashboard, go to the pages collection, and add a form block to the top of the home page. This form comes with a text, email, number, and textarea field. Let's add a date picker and an array field.
Update admin config
Array Block
Lets start by creating a new Block. Navigate to src/blocks/Form where the he pre-made form fields are. Create a file called blocks.ts. In this file we need to create the config for the Array block. We are going to reuse the same name, label, required, text, textArea, number, and width fields from the Payload repo. I just copy/pasted from there to maintain consistency in our custom field. I also used our dateOfBirth field from part 1 and renamed it to datePicker for our contact form. This is a giant wall of code but it's rather simple Payload config.
import type { Field, Block } from 'payload' export const name: Field = { name: 'name', type: 'text', label: 'Name (lowercase, no special characters)', required: true, } export const label: Field = { name: 'label', type: 'text', label: 'Label', localized: true, } export const required: Field = { name: 'required', type: 'checkbox', label: 'Required', } export const width: Field = { name: 'width', type: 'number', label: 'Field Width (percentage)', } export const TextArea: Block = { slug: 'textarea', fields: [ { type: 'row', fields: [ { ...name, admin: { width: '50%', }, }, { ...label, admin: { width: '50%', }, }, ], }, { type: 'row', fields: [ { ...width, admin: { width: '50%', }, }, { name: 'defaultValue', type: 'text', admin: { width: '50%', }, label: 'Default Value', localized: true, }, ], }, required, ], labels: { plural: 'Text Area Fields', singular: 'Text Area', }, } const Number: Block = { slug: 'number', fields: [ { type: 'row', fields: [ { ...name, admin: { width: '50%', }, }, { ...label, admin: { width: '50%', }, }, ], }, { type: 'row', fields: [ { ...width, admin: { width: '50%', }, }, { name: 'defaultValue', type: 'number', admin: { width: '50%', }, label: 'Default Value', }, ], }, required, ], labels: { plural: 'Number Fields', singular: 'Number', }, } const Text: Block = { slug: 'text', fields: [ { type: 'row', fields: [ { ...name, admin: { width: '50%', }, }, { ...label, admin: { width: '50%', }, }, ], }, { type: 'row', fields: [ { ...width, admin: { width: '50%', }, }, { name: 'defaultValue', type: 'text', admin: { width: '50%', }, label: 'Default Value', localized: true, }, ], }, required, ], labels: { plural: 'Text Fields', singular: 'Text', }, } const Email: Block = { slug: 'email', fields: [ { type: 'row', fields: [ { ...name, admin: { width: '50%', }, }, { ...label, admin: { width: '50%', }, }, ], }, width, required, ], labels: { plural: 'Email Fields', singular: 'Email', }, } export const DatePicker: Block = { slug: 'datePicker', fields: [ { type: 'row', fields: [ { ...name, admin: { width: '50%', }, }, { ...label, admin: { width: '50%', }, }, ], }, { type: 'row', fields: [ { ...width, admin: { width: '50%', }, }, { name: 'defaultValue', type: 'text', label: 'Default Value', admin: { width: '50%', }, }, ], }, required, ], labels: { plural: 'Date pickers', singular: 'Date picker', }, } export const ArrayBlock: Block = { slug: 'array', fields: [ { type: 'row', fields: [ { ...name, admin: { width: '33%', }, }, { name: 'label', type: 'text', label: 'Label Plural', required: true, admin: { width: '33%', }, }, { name: 'labelSingular', type: 'text', label: 'Label Singular', required: true, admin: { width: '33%', }, }, ], }, { type: 'row', fields: [], }, { type: 'row', fields: [ { ...width, defaultValue: 100, admin: { width: '33%', }, }, { name: 'minRows', type: 'number', label: 'Minimum Rows', required: true, defaultValue: 1, admin: { width: '33%', }, }, { name: 'maxRows', type: 'number', label: 'Maximum Rows', required: true, defaultValue: 4, admin: { width: '33%', }, }, ], }, { type: 'blocks', name: 'fields', label: 'Fields', blocks: [Text, TextArea, Number, Email, DatePicker], }, ], } Add Block to Plugin Config
Paul has the plugin configs in src/plugins/index. Simply add the block to the fields like this:
formBuilderPlugin({ fields: { payment: false, datePicker: DatePicker, array: ArrayBlock, }, // ... }) Test out the field in Admin Panel
It's going feel like we're already halfway there because we can now go to the form in the admin panel and add our new custom fields. Fill out the name and label, I'm using date and issues as the names. We can save but we don't see anything on the frontend yet.
Frontend Field Components
Date Picker
Type for DatePicker
Just need to make some small changes to our custom component from part 1. First we update the type.
// src/blocks/Form/DatePicker/type.ts export interface DatePickerField { blockName?: string blockType: 'datePicker' defaultValue?: string label?: string name: string required?: boolean width?: number } Shadcn ui components
Make sure you have the calendar and popover shadcn components.
pnpm dlx shadcn@latest add calendar popover
Remember we also updated our Calendar component for select fields for month and year. This isn't required for this form, but we'll reuse it anyway. So make sure your calendar component matches mine.
// src/components/ui/calendar.tsx "use client" import * as React from "react" import { ChevronLeft, ChevronRight } from "lucide-react" import { DayPicker } from "react-day-picker" import { cn } from "@/utilities/ui" import { buttonVariants } from "@/components/ui/button" export type CalendarProps = React.ComponentProps<typeof DayPicker> function Calendar({ className, classNames, showOutsideDays = true, ...props }: CalendarProps) { return ( <DayPicker showOutsideDays={showOutsideDays} className={cn("p-3", className)} classNames={{ months: "flex flex-col sm:flex-row space-y-4 sm:space-x-4 sm:space-y-0", month: "space-y-4", caption: "flex justify-center pt-1 relative items-center", caption_label: "text-sm font-medium", nav: "space-x-1 flex items-center", nav_button: cn( buttonVariants({ variant: "outline" }), "h-7 w-7 bg-transparent p-0 opacity-50 hover:opacity-100" ), nav_button_previous: "absolute left-1", nav_button_next: "absolute right-1", table: "w-full border-collapse space-y-1", head_row: "flex", head_cell: "text-muted-foreground rounded-md w-9 font-normal text-[0.8rem]", row: "flex w-full mt-2", cell: "h-9 w-9 text-center text-sm p-0 relative [&:has([aria-selected].day-range-end)]:rounded-r-md [&:has([aria-selected].day-outside)]:bg-accent/50 [&:has([aria-selected])]:bg-accent first:[&:has([aria-selected])]:rounded-l-md last:[&:has([aria-selected])]:rounded-r-md focus-within:relative focus-within:z-20", day: cn( buttonVariants({ variant: "ghost" }), "h-9 w-9 p-0 font-normal aria-selected:opacity-100" ), day_range_end: "day-range-end", day_selected: "bg-primary text-primary-foreground hover:bg-primary hover:text-primary-foreground focus:bg-primary focus:text-primary-foreground", day_today: "bg-accent text-accent-foreground", day_outside: "day-outside text-muted-foreground aria-selected:bg-accent/50 aria-selected:text-muted-foreground", day_disabled: "text-muted-foreground opacity-50", day_range_middle: "aria-selected:bg-accent aria-selected:text-accent-foreground", day_hidden: "invisible", ...classNames, }} components={{ IconLeft: ({ className, ...props }) => ( <ChevronLeft className={cn("h-4 w-4", className)} {...props} /> ), IconRight: ({ className, ...props }) => ( <ChevronRight className={cn("h-4 w-4", className)} {...props} /> ), }} {...props} /> ) } Calendar.displayName = "Calendar" export { Calendar } DatePicker component
Make sure this is reflected in the component.
// src/blocks/Form/DatePicker/index.tsx import type { DatePickerField } from './type' import type { Control, FieldErrorsImpl, FieldValues } from 'react-hook-form' import { Label } from '@/components/ui/label' import React from 'react' import { Controller } from 'react-hook-form' import { CalendarIcon } from 'lucide-react' import { format } from 'date-fns' import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover' import { Button } from '@/components/ui/button' import { Calendar } from '@/components/ui/calendar' import { cn } from '@/utilities/ui' import { Error } from '../Error' import { Width } from '../Width' export const DatePicker: React.FC< DatePickerField & { control: Control<FieldValues, any> errors: Partial< FieldErrorsImpl<{ [x: string]: any }> > } > = ({ name, control, errors, label, required, width, defaultValue }) => { const [open, setOpen] = React.useState(false) return ( <Width width={width}> <Label htmlFor={name}>{label}</Label> <Controller control={control} defaultValue={defaultValue} name={name} shouldUnregister // this is very important for state consistency when used in an array render={({ field }) => ( <Popover open={open} onOpenChange={setOpen}> <PopoverTrigger asChild> <Button variant="outline" className={cn( 'w-full pl-3 text-left font-normal', !field.value && 'text-muted-foreground', )} > {field.value ? format(field.value, 'dd/MM/yyyy') : <span>Pick a date</span>} <CalendarIcon className="ml-auto h-4 w-4 opacity-50" /> </Button> </PopoverTrigger> <PopoverContent className="w-auto p-0"> <Calendar mode="single" selected={field.value} onSelect={(date) => { field.onChange(date) setOpen(false) }} disabled={(date) => date > new Date() || date < new Date('1900-01-01')} initialFocus captionLayout="dropdown-buttons" fromYear={1950} toYear={new Date().getFullYear()} classNames={{ dropdown: 'rdp-dropdown bg-card rounded-md border !px-2', dropdown_icon: 'ml-2', dropdown_year: 'rdp-dropdown_year ml-3', dropdown_month: '', }} /> </PopoverContent> </Popover> )} rules={{ required }} /> <div className="min-h-[24px]">{required && errors[name] && <Error />}</div> </Width> ) } Array
Types for Array Component
Let's create the types.
// src/blocks/Form/Array/types.ts import { BlockConfig } from '@payloadcms/plugin-form-builder/types' export type ArrayEntryField = { blockType: 'datePicker' | 'textArea' name: string label: string required?: boolean width?: number } export interface ArrayBlockConfig extends BlockConfig { blockType: 'array' name: string label: string labelSingular: string minRows: number maxRows: number width?: number fields: ArrayEntryField[] } Array Component
This is our main Array component. Inside it we are using the ArrayField components. We are also using motion for smooth animations.
// src/blocks/Form/Array/index.tsx 'use client' import React, { useEffect } from 'react' import { useFieldArray, useFormContext } from 'react-hook-form' import { ArrayField } from './ArrayField' import { Button } from '@/components/ui/button' import { CardContent, CardHeader, CardTitle } from '@/components/ui/card' import { Plus } from 'lucide-react' import { ArrayBlockConfig } from './types' import { motion, AnimatePresence } from 'motion/react' import { cn } from '@/utilities/ui' export const Array: React.FC<ArrayBlockConfig> = (props) => { const { label, maxRows = 10, minRows = 0, name } = props const { register, control, formState: { errors }, } = useFormContext() const { fields, append, remove } = useFieldArray({ control, name: name, shouldUnregister: true, }) useEffect(() => { if (minRows > 0 && fields.length === 0) { append({}) } }, [append, fields.length, minRows]) return ( <div> <CardHeader className="flex flex-row items-center justify-between px-0"> <CardTitle>{label}</CardTitle> </CardHeader> <CardContent className="flex flex-col gap-4 px-0"> <AnimatePresence initial={false} mode="sync"> {fields.map((field, index) => ( <motion.div initial={{ opacity: 0, height: 0 }} animate={{ opacity: 1, height: 'auto' }} exit={{ opacity: 0, height: 0, transition: { duration: 0.3 }, }} layout transition={{ duration: 0.3 }} key={field.id} className="rounded-lg border p-4" > <ArrayField index={index} register={register} errors={errors} {...props} control={control} remove={remove} currentRows={fields.length} /> </motion.div> ))} </AnimatePresence> <Button type="button" size="icon" className={cn( 'size-7 rounded-full bg-gray-400 transition-opacity duration-300 hover:bg-gray-500', { 'pointer-events-none opacity-0': fields.length >= maxRows, 'opacity-100': fields.length < maxRows, }, )} onClick={() => append({})} > <Plus className="h-4 w-4 text-black" /> </Button> </CardContent> </div> ) } Install motion
We should make this a smooth animation when adding and removing fields, so lets install the motion package
pnpm i motion
Array field
Each input field in the array field needs to be handled in this component.
// src/blocks/Form/Array/ArrayField.tsx import React from 'react' import type { FieldErrorsImpl, FieldValues, UseFormRegister } from 'react-hook-form' import { CardDescriptionDiv } from '@/components/ui/card' import type { ArrayEntryField } from './types' import { Button } from '@/components/ui/button' import { Trash2 } from 'lucide-react' import { cn } from '@/utilities/ui' import { DatePicker } from '../DatePicker' import { Textarea } from '../Textarea' interface ArrayFieldsProps { index: number name: string fields: ArrayEntryField[] labelSingular: string label: string errors: Partial<FieldErrorsImpl<{ [x: string]: any }>> register: UseFormRegister<FieldValues> control: any remove: (index: number) => void minRows: number currentRows: number } type FieldComponentType = ArrayEntryField['blockType'] const fieldComponents: Record<FieldComponentType, React.ComponentType<any>> = { datePicker: DatePicker, textArea: Textarea, } as const export const ArrayField: React.FC<ArrayFieldsProps> = ({ index, fields, register, name, errors, labelSingular, control, remove, minRows, currentRows, }) => { const renderField = (fieldItem: ArrayEntryField, fieldIndex: number) => { const Field = fieldComponents[fieldItem.blockType] if (Field) { const fieldName = `${name}[${index}].${fieldItem.name}` const wrappedErrors = { [fieldName]: (errors?.[name] as any)?.[index]?.[fieldItem.name], } return ( <Field {...(fieldItem as any)} name={fieldName} control={control} errors={wrappedErrors} register={register} /> ) } return null } return ( <div className=""> <CardDescriptionDiv className="flex items-center justify-between"> {labelSingular} {index + 1} <Button type="button" variant="ghost" size="icon" className={cn('size-7 rounded-full transition-opacity hover:bg-red-100', { 'pointer-events-none opacity-0': currentRows <= minRows, 'opacity-100': currentRows > minRows, })} onClick={() => remove(index)} > <Trash2 className="size-4 text-red-700 hover:text-red-900" /> </Button> </CardDescriptionDiv> <div className="flex flex-wrap gap-x-4 gap-y-2"> {fields.map((fieldItem, fieldIndex) => ( <React.Fragment key={fieldIndex}>{renderField(fieldItem, fieldIndex)}</React.Fragment> ))} </div> </div> ) } fields.tsx
We need to update the map function to include our DatePicker and Array components.
// src blocks/Form/fields.tsx import { Checkbox } from './Checkbox' import { Country } from './Country' import { DatePicker } from './DatePicker' import { Email } from './Email' import { Message } from './Message' import { Number } from './Number' import { Select } from './Select' import { State } from './State' import { Text } from './Text' import { Textarea } from './Textarea' import { Array } from './Array' export const fields = { checkbox: Checkbox, country: Country, email: Email, message: Message, number: Number, select: Select, state: State, text: Text, textarea: Textarea, datePicker: DatePicker, array: Array } Form Submission
We are going to make our lives easier by using a json field for our data. There will be a couple steps, but this also makes it incredibly easy to use a custom component for form submissions if we want later.
onSubmit()
in the main form component we need to update the onSubmit() to post are data to submissionData. Also use the email field for our title.
// src/blocks/Component.tsx // ...beginning of file const onSubmit = useCallback( (data: FormFieldBlock[]) => { let loadingTimerID: ReturnType<typeof setTimeout> const submitForm = async () => { setError(undefined) // delay loading indicator by 1s loadingTimerID = setTimeout(() => { setIsLoading(true) }, 1000) try { // @ts-expect-error const title = data.email ? data.email : new Date().toISOString() const req = await fetch(`${getClientSideURL()}/api/form-submissions`, { body: JSON.stringify({ title, form: formID, submissionData: data, }), headers: { 'Content-Type': 'application/json', }, method: 'POST', }) const res = await req.json() // ...rest of function void submitForm() }, [router, formID, redirect, confirmationType], ) // ...rest of file formS
Last we need to update the config for the form submission collection. We are grabbing the name field and adding a title and json data.
formSubmissionOverrides: { admin: { useAsTitle: 'title', }, fields: ({ defaultFields }) => { const formField = defaultFields.find((field) => 'name' in field && field.name === 'form') return [ ...(formField ? [formField] : []), { name: 'title', type: 'text', }, { name: 'submissionData', type: 'json', }, ] }, }, 
Conclusion
There is a lot of code and files to get this working. On top of that it required a good understanding of react-hook-forms and the motion library. Quite a few gotchas along the way. Maybe someone can help with he month/year drop down text color being too light in dark mode.
Super easy to add a custom component from here for the form submissions. What I want to improve is the fact I don't know the names of the fields a head of time to make it truly dynamic. Let me know your thoughts.
Top comments (0)