Form Builder for ApostropheCMS

Let content teams build and manage forms without developer intervention. Editors can create contact forms, surveys, applications, and registrations directly in the CMS, then place them anywhere on your site. Forms automatically handle submissions, email notifications, validation, and spam protection.

Why Form Builder?

• No-Code Form Creation: Editors build forms through configurable field widgets—no tickets to developers
• Automatic Data Collection: Submissions saved to MongoDB with optional email notifications
• 🛡️ Built-in Security: reCAPTCHA v3 integration and validation prevent spam
• Design Freedom: Custom CSS classes and styling hooks for brand consistency
• Developer-Friendly: Event hooks, custom validators, and extensible field types
• Email Ready: Route submissions to multiple recipients automatically

Table of Contents

• Installation
• Usage
  • Module Configuration
  • How It Works
  • Adding Form Widget to Areas
  • Editor Workflow
• Configuration
  • Main Module Options
  • Available Field Types
• Handling Submissions
  • Database Storage
  • Email Notifications
  • Server-Side Events
  • Browser Events
• reCAPTCHA Integration
  • Configuration Options
• Styling
  • Custom CSS Classes
• Field-Specific Options
  • Select Field
  • File Upload Field
• Custom Field Validation
  • Extending Collectors with the Super Pattern
  • Example: Minimum Word Count Validation
  • Error Handling
• Use Cases
• 💎 Ready for More?
  • 🚀 Pro Features for Forms

Installation

Usage

Module Configuration

Configure the form modules in your app.js file:

Module order matters: @apostrophecms/form must appear before the widget modules. Include only the field types you want editors to use.

How It Works

The @apostrophecms/form module creates a new piece-type called "Forms" in your CMS. This means forms are content that editors create once and can reuse across multiple pages—just like blog posts or products. Create a "Contact Form" once, then place it on your contact page, footer, and sidebar using the form widget.

Adding Form Widget to Areas

To let editors add forms to a page or piece-type, include the form widget in an area:

Editor Workflow

Once configured, editors can create and manage forms:

1. Create a form: Click "Forms" in the admin bar and create a new form (e.g., "Contact Form")
2. Build the form: Add field widgets (text fields, email, checkboxes, etc.) and configure options
3. Configure submission handling: Set up email notifications and confirmation messages in the "After-Submission" tab
4. Place the form: Edit any page with a form area, add the form widget, and select your created form

Editors can now create and manage forms independently.

Configuration

Main Module Options

Configure @apostrophecms/form with these options:

Available Field Types

The formWidgets option controls which widgets editors can use when building forms. Configure this in your project-level /modules/@apostrophecms/form/index.js file to override the built-in defaults. This is a global setting that applies to all forms in your project.

Default configuration:

The rich text widget allows editors to add instructions within forms. Any widget type can be included in this configuration.

Need different field types for different forms? The formWidgets option is global and cannot be set per-area or per-page. If you need separate sets of allowed fields (for example, a simple contact form vs. a detailed application form), extend the @apostrophecms/form module to create a second form piece-type with its own formWidgets configuration. However, without additional controls, all editors can use both form types. Use @apostrophecms-pro/advanced-permission to restrict which user groups can create and manage each form type—ensuring junior editors only access basic forms while senior staff can use advanced forms. Learn more about Pro features.

Handling Submissions

Database Storage

Submissions are automatically saved to the aposFormSubmissions MongoDB collection. To disable database storage:

Email Notifications

If @apostrophecms/email is configured, forms can automatically email submissions to multiple recipients. In the form editor, navigate to the "After-Submission" tab and enter comma-separated email addresses in the "Email Address(es) for Results" field.

To hide email notification fields:

📧 Email Configuration: To send form submissions via email, you must first configure the @apostrophecms/email module. See the email configuration guide for setup instructions. Forms can still save submissions to the database without email configuration.

Server-Side Events

Form submissions trigger events you can handle in your code for custom processing, integrations, or modifying submission data. For example, you could send submissions to an external CRM, add server-side metadata like query parameters, or trigger custom workflows.

submission event - Fires on every form submission:

beforeSaveSubmission event - Fires before saving the info.submission to the database (if enabled):

Event handler arguments:

Browser Events

The form module emits browser events on the body element after a submission attempt. You can listen for these to add custom client-side feedback or analytics.

Success Event

@apostrophecms/form:submission-form Fires when a submission is successfully processed. The event detail includes a form property.

Failure Event

@apostrophecms/form:submission-failed Fires when a submission fails due to validation errors, spam protection, or server issues. The event detail includes a formError property.

Use Cases

• Replace the default "thank you" UI with a custom success message
• Push events into Google Tag Manager, Segment, or other analytics
• Redirect or scroll the page after a successful submission
• Display tailored error messages on failure

Note: Forms already support built-in after-submission messages (thankYouHeading, thankYouBody) and inline error handling. You only need these browser events if you want extra client-side behavior beyond what the module provides out of the box.

reCAPTCHA Integration

Protect forms from spam with Google reCAPTCHA v3. Set up reCAPTCHA at google.com/recaptcha using version 3, then configure your site and secret keys.

Configuration Options

Option 1: Hard-code in module configuration

Option 2: Allow editors to configure in UI

If you don't hard-code both keys, a global settings UI appears where admins can enter them. Once configured, each form has a checkbox to enable reCAPTCHA independently.

Styling

Custom CSS Classes

Add your own class prefix to form elements for complete styling control:

This generates BEM-style classes like my-form__input, my-form__label, and my-form__error on form elements.

For teams who prefer visual design tools, the Palette extension allows in-context CSS customization without writing code. Learn more about Pro features.

Field-Specific Options

Select Field

The select field widget supports multiple selections:

When enabled, two additional fields appear in the widget schema:

File Upload Field

⚠️ Security Warning: File upload fields allow any visitor to upload files to your server, creating potential risks for storage abuse and malicious uploads. This widget is not included by default—you must explicitly enable it.

Where to implement security measures:

ApostropheCMS attachment module (modules/@apostrophecms/attachment/index.js):

See the attachment module documentation for complete configuration options.

Form submission handler (for additional validation):

Files are stored in your configured attachment storage (local uploads or cloud bucket). Form submissions save attachment URLs, not the files themselves.

Multiple file uploads: Like the select field, the file field widget supports an allowMultiple option:

When enabled, users can select and upload multiple files in a single form submission.

Custom Field Validation

Need business-specific rules like minimum word counts, format requirements, or cross-field dependencies? Extend the built-in field collectors to add custom validation logic before submission. This runs client-side for immediate feedback without server round-trips.

Each field returns its value from a collector function located on the apos.aposForm.collectors array in the browser. You can extend these collector functions to adjust the value or do additional validation before the form posts to the server. Collector functions can be written as asynchronous functions if needed.

Collector functions take the widget element as an argument and return a response object on a successful submission. The response object properties are:

Extending Collectors with the Super Pattern

These functions can be extended for project-level validation using the super pattern. This involves:

1. Assigning the original function to a variable
2. Creating a new function that uses the original one, adds functionality, and returns an identically structured response
3. Assigning the new function to the original function property

Example: Minimum Word Count Validation

Error Handling

If you want to indicate an error on the field, throw an object with the following values (as shown above):

Use Cases

Contact Forms: Let teams create department-specific contact forms without developer involvement.

Lead Generation: Build conversion-optimized forms with conditional fields and reCAPTCHA protection.

Event Registration: Collect attendee information with file uploads for documents or photos.

User Feedback: Create surveys and feedback forms that route to appropriate team members.

Job Applications: Accept resumes and application materials with validation and email routing.

💎 Ready for More?

The open-source form builder provides powerful form creation capabilities, but enterprise teams often need advanced control and workflow features. ApostropheCMS Pro extends form functionality with professional-grade features:

🚀 Pro Features for Forms

• 🔐 Advanced Permissions - Control which teams can create, edit, and manage specific form types. Restrict access to sensitive forms like HR applications or customer data collection. Perfect for multi-team organizations that need different form capabilities for different departments.

• 🌍 Automated Translation - Automatically translate forms and confirmation messages into multiple languages with AI-powered translation services (DeepL, Google Translate, Azure). Deploy multilingual forms without manual translation work.

• 📄 Document Management - Version control for forms with complete audit trails. Track changes to form fields, restore previous versions, and maintain compliance with form modification history.

• 🎨 Visual Design Tools - Use the Palette extension for in-context CSS customization of form styling without writing code. Perfect for teams without dedicated frontend developers.

Create an account on Apostrophe Workspaces and upgrade to ApostropheCMS Pro or contact our team to learn about Pro licensing and access enterprise features that enhance form management, compliance, and team collaboration.