Simplify your stack and build anything. Or everything.
Schedule a Demo
USE CASES
Headless CMSEnterprise App BuilderHeadless E-CommerceDigital Asset Management
FEATURES
Multi-TenancyWhite LabelLocalizationAccess ControlAuth
CASE STUDIES

See what others are building with Payload.

Browse Case Studies
Build tomorrow’s web with a modern solution you truly own.
PAYLOAD IS FOR
DevelopersMarketing teamsEnterprise companiesAgencies & Consultancies
COMPARE PAYLOAD
Payload vs WordPressPayload vs ContentfulPayload vs SanityPayload vs StrapiPayload vs Directus
AGENCY TESTIMONIAL

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Become a PartnerFind a Partner
Code-based nature means you can build on top of it to power anything.
Resources
DocumentationExamplesTemplatesGitHubReleasesBlog
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
LoginNew Project

Form Builder Plugin

NPM

This plugin allows you to build and manage custom forms directly within the Admin Panel. Instead of hard-coding a new form into your website or application every time you need one, admins can simply define the schema for each form they need on-the-fly, and your front-end can map over this schema, render its own UI components, and match your brand's design system.

All form submissions are stored directly in your database and are managed directly from the Admin Panel. When forms are submitted, you can display a custom on-screen confirmation message to the user or redirect them to a dedicated confirmation page. You can even send dynamic, personalized emails derived from the form's data. For example, you may want to send a confirmation email to the user who submitted the form, and also send a notification email to your team.

Forms can be as simple or complex as you need, from a basic contact form, to a multi-step lead generation engine, or even a donation form that processes payment. You may not need to reach for third-party services like HubSpot or Mailchimp for this, but instead use your own first-party tooling, built directly into your own application.

Core Features
  • Build completely dynamic forms directly from the Admin Panel for a variety of use cases
  • Render forms on your front-end using your own UI components and match your brand's design system
  • Send dynamic, personalized emails upon form submission to multiple recipients, derived from the form's data
  • Display a custom confirmation message or automatically redirect upon form submission
  • Build dynamic prices based on form input to use for payment processing (optional)

Installation

Install the plugin using any JavaScript package manager like Yarn, NPM, or PNPM:

1
pnpm add @payloadcms/plugin-form-builder

Basic Usage

In the plugins array of your Payload Config, call the plugin with options:

1
import { buildConfig } from 'payload'
2
import { formBuilderPlugin } from '@payloadcms/plugin-form-builder'
3
4
const config = buildConfig({
5
collections: [
6
{
7
slug: 'pages',
8
fields: [],
9
},
10
],
11
plugins: [
12
formBuilderPlugin({
13
// see below for a list of available options
14
}),
15
],
16
})
17
18
export default config

Options

fields (option)

The fields property is an object of field types to allow your admin editors to build forms with. To override default settings, pass either a boolean value or a partial Payload Block keyed to the block's slug. See Fields for more details.

1
// payload.config.ts
2
formBuilder({
3
// ...
4
fields: {
5
text: true,
6
textarea: true,
7
select: true,
8
email: true,
9
state: true,
10
country: true,
11
checkbox: true,
12
number: true,
13
message: true,
14
payment: false,
15
},
16
})

redirectRelationships

The redirectRelationships property is an array of collection slugs that, when enabled, are populated as options in the form's redirect field. This field is used to redirect the user to a dedicated confirmation page upon form submission (optional).

1
// payload.config.ts
2
formBuilder({
3
// ...
4
redirectRelationships: ['pages'],
5
})

beforeEmail

The beforeEmail property is a beforeChange hook that is called just after emails are prepared, but before they are sent. This is a great place to inject your own HTML template to add custom styles.

1
// payload.config.ts
2
formBuilder({
3
// ...
4
beforeEmail: (emailsToSend, beforeChangeParams) => {
5
// modify the emails in any way before they are sent
6
return emails.map((email) => ({
7
...email,
8
html: email.html, // transform the html in any way you'd like (maybe wrap it in an html template?)
9
}))
10
},
11
})

For full types with beforeChangeParams, you can import the types from the plugin:

1
import type { BeforeEmail } from '@payloadcms/plugin-form-builder'
2
// Your generated FormSubmission type
3
import type {FormSubmission} from '@payload-types'
4
5
// Pass it through and 'data' or 'originalDoc' will now be typed
6
const beforeEmail: BeforeEmail<FormSubmission> = (emailsToSend, beforeChangeParams) => {
7
// modify the emails in any way before they are sent
8
return emails.map((email) => ({
9
...email,
10
html: email.html, // transform the html in any way you'd like (maybe wrap it in an html template?)
11
}))
12
}

defaultToEmail

Provide a fallback for the email address to send form submissions to. If the email in form configuration does not have a to email set, this email address will be used. If this is not provided then it falls back to the defaultFromAddress in your email configuration.

1
// payload.config.ts
2
formBuilder({
3
// ...
4
defaultToEmail: 'test@example.com',
5
})

formOverrides

Override anything on the forms collection by sending a Payload Collection Config to the formOverrides property.

Note that the fields property is a function that receives the default fields and returns an array of fields. This is because the fields property is a special case that is merged with the default fields, rather than replacing them. This allows you to map over default fields and modify them as needed.

1
// payload.config.ts
2
formBuilder({
3
// ...
4
formOverrides: {
5
slug: 'contact-forms',
6
access: {
7
read: ({ req: { user } }) => !!user, // authenticated users only
8
update: () => false,
9
},
10
fields: ({ defaultFields }) => {
11
return [
12
...defaultFields,
13
{
14
name: 'custom',
15
type: 'text',
16
},
17
]
18
},
19
},
20
})

formSubmissionOverrides

Override anything on the form-submissions collection by sending a Payload Collection Config to the formSubmissionOverrides property.

1
// payload.config.ts
2
formBuilder({
3
// ...
4
formSubmissionOverrides: {
5
slug: 'leads',
6
fields: ({ defaultFields }) => {
7
return [
8
...defaultFields,
9
{
10
name: 'custom',
11
type: 'text',
12
},
13
]
14
},
15
},
16
})

handlePayment

The handlePayment property is a beforeChange hook that is called upon form submission. You can integrate into any third-party payment processing API here to accept payment based on form input. You can use the getPaymentTotal function to calculate the total cost after all conditions have been applied. This is only applicable if the form has enabled the payment field.

First import the utility function. This will execute all of the price conditions that you have set in your form's payment field and returns the total price.

1
// payload.config.ts
2
import { getPaymentTotal } from '@payloadcms/plugin-form-builder'

Then in your plugin's config:

1
// payload.config.ts
2
formBuilder({
3
// ...
4
handlePayment: async ({ form, submissionData }) => {
5
// first calculate the price
6
const paymentField = form.fields?.find((field) => field.blockType === 'payment')
7
const price = getPaymentTotal({
8
basePrice: paymentField.basePrice,
9
priceConditions: paymentField.priceConditions,
10
fieldValues: submissionData,
11
})
12
// then asynchronously process the payment here
13
},
14
})

Fields

Each field represents a form input. To override default settings pass either a boolean value or a partial Payload Block keyed to the block's slug. See Field Overrides for more details on how to do this.

Text

Maps to a text input in your front-end. Used to collect a simple string.

PropertyTypeDescription
namestringThe name of the field.
labelstringThe label of the field.
defaultValuestringThe default value of the field.
widthstringThe width of the field on the front-end.
requiredcheckboxWhether or not the field is required when submitted.

Textarea

Maps to a textarea input on your front-end. Used to collect a multi-line string.

PropertyTypeDescription
namestringThe name of the field.
labelstringThe label of the field.
defaultValuestringThe default value of the field.
widthstringThe width of the field on the front-end.
requiredcheckboxWhether or not the field is required when submitted.

Select

Maps to a select input on your front-end. Used to display a list of options.

PropertyTypeDescription
namestringThe name of the field.
labelstringThe label of the field.
defaultValuestringThe default value of the field.
widthstringThe width of the field on the front-end.
requiredcheckboxWhether or not the field is required when submitted.
optionsarrayAn array of objects with label and value properties.

Email (field)

Maps to a text input with type email on your front-end. Used to collect an email address.

PropertyTypeDescription
namestringThe name of the field.
labelstringThe label of the field.
defaultValuestringThe default value of the field.
widthstringThe width of the field on the front-end.
requiredcheckboxWhether or not the field is required when submitted.

State

Maps to a select input on your front-end. Used to collect a US state.

PropertyTypeDescription
namestringThe name of the field.
labelstringThe label of the field.
defaultValuestringThe default value of the field.
widthstringThe width of the field on the front-end.
requiredcheckboxWhether or not the field is required when submitted.

Country

Maps to a select input on your front-end. Used to collect a country.

PropertyTypeDescription
namestringThe name of the field.
labelstringThe label of the field.
defaultValuestringThe default value of the field.
widthstringThe width of the field on the front-end.
requiredcheckboxWhether or not the field is required when submitted.

Checkbox

Maps to a checkbox input on your front-end. Used to collect a boolean value.

PropertyTypeDescription
namestringThe name of the field.
labelstringThe label of the field.
defaultValuecheckboxThe default value of the field.
widthstringThe width of the field on the front-end.
requiredcheckboxWhether or not the field is required when submitted.

Number

Maps to a number input on your front-end. Used to collect a number.

PropertyTypeDescription
namestringThe name of the field.
labelstringThe label of the field.
defaultValuenumberThe default value of the field.
widthstringThe width of the field on the front-end.
requiredcheckboxWhether or not the field is required when submitted.

Message

Maps to a RichText component on your front-end. Used to display an arbitrary message to the user anywhere in the form.

propertytypedescription
messagerichTextThe message to display on the form.

Payment

Add this field to your form if it should collect payment. Upon submission, the handlePayment callback is executed with the form and submission data. You can use this to integrate with any third-party payment processing API.

propertytypedescription
namestringThe name of the field.
labelstringThe label of the field.
defaultValuenumberThe default value of the field.
widthstringThe width of the field on the front-end.
requiredcheckboxWhether or not the field is required when submitted.
priceConditionsarrayAn array of objects that define the price conditions. See below for more details.

Price Conditions

Each of the priceConditions are executed by the getPaymentTotal utility that this plugin provides. You can call this function in your handlePayment callback to dynamically calculate the total price of a form upon submission based on the user's input. For example, you could create a price condition that says "if the user selects 'yes' for this checkbox, add $10 to the total price".

propertytypedescription
fieldToUserelationshipThe field to use to determine the price.
conditionstringThe condition to use to determine the price.
valueForOperatorstringThe value to use for the operator.
operatorstringThe operator to use to determine the price.
valueTypestringThe type of value to use to determine the price.
valuestringThe value to use to determine the price.

Field Overrides

You can provide your own custom fields by passing a new Payload Block object into fields. You can override or extend any existing fields by first importing the fields from the plugin:

1
import { fields } from '@payloadcms/plugin-form-builder'

Then merging it into your own custom field:

1
// payload.config.ts
2
formBuilder({
3
// ...
4
fields: {
5
text: {
6
...fields.text,
7
labels: {
8
singular: 'Custom Text Field',
9
plural: 'Custom Text Fields',
10
},
11
},
12
},
13
})

Email

This plugin relies on the email configuration defined in your payload configuration. It will read from your config and attempt to send your emails using the credentials provided.

Email formatting

The email contents supports rich text which will be serialized to HTML on the server before being sent. By default it reads the global configuration of your rich text editor.

The email subject and body supports inserting dynamic fields from the form submission data using the {{field_name}} syntax. For example, if you have a field called name in your form, you can include this in the email body like so:

1
Thank you for your submission, {{name}}!

You can also use {{*}} as a wildcard to output all the data in a key:value format and {{*:table}} to output all the data in a table format.

TypeScript

All types can be directly imported:

1
import type {
2
PluginConfig,
3
Form,
4
FormSubmission,
5
FieldsConfig,
6
BeforeEmail,
7
HandlePayment,
8
...
9
} from "@payloadcms/plugin-form-builder/types";

Examples

The Examples Directory contains an official Form Builder Plugin Example which demonstrates exactly how to configure this plugin in Payload and implement it on your front-end. We've also included an in-depth walk-through of how to build a form from scratch in our Form Builder Plugin Blog Post.

Troubleshooting

Below are some common troubleshooting tips. To help other developers, please contribute to this section as you troubleshoot your own application.

SendGrid 403 Forbidden Error
  • If you are using SendGrid Link Branding to remove the "via sendgrid.net" part of your email, you must also setup Domain Authentication. This means you can only send emails from an address on this domain — so the from addresses in your form submission emails cannot be anything other than something@your_domain.com. This means that from {{email}} will not work, but website@your_domain.com will. You can still send the form's email address in the body of the email.

Screenshots

screenshot 1


screenshot 2


screenshot 3


screenshot 4


screenshot 5


screenshot 6

Next

Nested Docs Plugin