Payload Plugin Forms v3

A flexible forms plugin for Payload CMS v3. Create and manage forms with configurable fields, email settings, and feedback messages.

Features

• Create and manage forms with multiple field types
• Configurable field widths (1/1, 1/2, 1/4, 3/4)
• Sender/receiver email configuration
• Customizable success and error messages
• Conditional field display
• Autocomplete attribute support
• Full i18n support (EN, DE, ES, FR, NL)
• Optional field localization

Installation

npm install @art-design-digital/payload-plugin-forms-v3
# or
pnpm add @art-design-digital/payload-plugin-forms-v3
# or
yarn add @art-design-digital/payload-plugin-forms-v3

Usage

Add the plugin to your Payload config:

import { buildConfig } from 'payload'
import { formsPlugin } from '@art-design-digital/payload-plugin-forms-v3'

export default buildConfig({
  // ... your config
  plugins: [
    formsPlugin({
      // Optional: Admin group name
      adminGroup: 'Content',
      // Optional: Enable localization for form field labels
      localized: true,
      // Optional: Override access control
      access: {
        read: () => true,
        create: ({ req }) => req.user?.role === 'admin',
        update: ({ req }) => req.user?.role === 'admin',
        delete: ({ req }) => req.user?.role === 'admin',
      },
      // Optional: Disable the plugin (keeps schema for migrations)
      disabled: false,
    }),
  ],
})

Configuration Options

| Option | Type | Default | Description | | ------------ | ---------------------------- | ---------------------- | ---------------------------------------------------- | | adminGroup | string | undefined | Admin panel group name for the Forms collection | | localized | boolean | false | Enable localization for form field labels | | access | CollectionConfig['access'] | { read: () => true } | Override access control for the Forms collection | | disabled | boolean | false | Disable the plugin (schema preserved for migrations) |

Form Field Types

The plugin supports these field types:

| Type | Description | | ---------- | ------------------------------- | | text | Single-line text input | | textarea | Multi-line text input | | email | Email input with validation | | number | Numeric input with min/max/step | | tel | Telephone number input | | url | URL input with validation | | dropdown | Select dropdown with options | | radio | Radio button group | | checkbox | Single checkbox | | date | Date picker | | time | Time picker | | datetime | Date and time picker |

Form Field Configuration

Each form field can be configured with:

| Field | Description | | -------------- | --------------------------------------------------------- | | label | Display label for the field | | fieldType | Type of field (see above) | | width | Field width: full, half, onequarter, threequarter | | required | Whether the field is required | | placeholder | Placeholder text | | description | Help text below the field | | default | Default value | | autocomplete | HTML autocomplete attribute | | condition | Conditional display based on another field's value |

Type-specific options

• text/textarea: minLength, maxLength, rows (textarea only)
• number: minValue, maxValue, step
• dropdown/radio: options array with label and value
• date/datetime: minDate, maxDate

Form Structure

Each form includes:

Form Fields

An array of configurable form fields with the options described above.

Sender/Receiver Settings

• senderName - Name shown in email "From" field
• senderMail - Email address for the sender
• receiver - Email address(es) to receive submissions
• subject - Email subject line

Messages

• submitLabel - Text for the submit button
• successMessage - Message shown on successful submission
• errorMessage - Message shown on submission error

Fetching Forms

You can fetch forms using the Payload Local API or REST API:

// Local API
const forms = await payload.find({
  collection: 'forms',
  where: {
    name: { equals: 'Contact Form' },
  },
})

// REST API
// GET /api/forms?where[name][equals]=Contact Form

i18n Support

The plugin includes translations for:

• English (en)
• German (de)
• Spanish (es)
• French (fr)
• Dutch (nl)

All field labels, validation messages, and UI elements are translated based on your Payload admin language setting.

TypeScript

The plugin exports types for use in your project:

import type {
  FormsPluginConfig,
  Form,
  FormField,
  FormFieldOption,
  AutocompleteValue,
  FormFieldCondition,
} from '@art-design-digital/payload-plugin-forms-v3'

import { FIELD_TYPES, WIDTHS } from '@art-design-digital/payload-plugin-forms-v3'

License

MIT