> For the complete documentation index, see [llms.txt](https://www.one.thezero.club/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.one.thezero.club/guide/form-builder.md).

# Form Builder

Zero One includes a customized integration of the excellent Form Block Suite plugin created by [Plain Solutions](https://github.com/plain-solutions-gmbh), allowing editors to build forms visually using Kirby blocks. 

{% hint style="info" %}
**Good news!** Starting with Zero One version 5.5.0, Form Builder is included free of charge. No additional license purchase or activation is required. 

Users upgrading from older Zero One versions may still find references to the former premium licensing model in older documentation and videos.
{% endhint %}

***

### Main Features

The Form Builder comes packed with a wide range of features:

* Build forms directly from the Kirby Panel.
* Organize form fields visually.
* Use multiple forms on the same page.
* Display and manage submitted requests within the Panel.
* Receive email notifications for new submissions.
* Send confirmation emails to visitors.
* Customize form messages and email templates.
* Export submissions as CSV.
* Protect forms with an integrated honeypot anti-spam system.
* CAPTCHA field: math puzzle, reCAPTCHA (since v6) or hCaptcha (since v6).
* Perform client-side validation without reloading the page.
* Full multilingual support.
* Extend the plugin with custom field types.

{% hint style="info" %}
Most websites can build contact forms, quote request forms, booking inquiries, support forms, newsletter signups, and application forms without any custom development.
{% endhint %}

***

### Creating Your First Form

Form Builder is available as a Kirby block and can be added anywhere blocks are supported.

Simply:

1. Open a page in the Panel.
2. Add a new block.
3. Select **Form Builder**.
4. Add the fields you need.
5. Configure notifications and messages.
6. Save the page.

Your form is immediately ready to receive submissions.

***

### Email Sending

When a visitor submits a form, Form Builder can send email notifications.

By default, outgoing mail uses:

```
no-reply@your-domain.com
```

If you want to specify a custom sender address, add the following to your config:

{% code title="config.your-domain.com.php " %}

```php
return [

    'plain.formblock' => [
        'from_email' => [
            'info@example.com' => 'Your Website'
        ]
    ],

];
```

{% endcode %}

***

### SMTP Configuration

Many hosting providers no longer allow reliable sending through PHP mail.

If emails are not arriving, configure SMTP in Kirby.

We strongly recommend reading:

👉 [SMTP Email Options](/guide/installation/smtp-email-options.md)

Once SMTP is configured correctly, Form Builder will automatically use Kirby's email system.

***

### Form Builder Configuration

Form Block Suite includes many additional configuration options, including:

* Custom email templates.
* Translation overrides.
* Validation settings.
* Spam protection.
* Dynamic validation.
* Success hooks.
* Custom messages.

For a complete list of available options, see the [plugin documentation on GitHub](https://github.com/plain-solutions-gmbh/kirby-form-block-suite).

***

### Translating Messages

Zero One allows many texts to be configured directly inside the block settings.

For advanced multilingual projects, additional translations can be configured through Kirby's configuration files.

This is particularly useful when creating websites with multiple languages and customized user-facing messages. 

***

### CAPTCHA Protection

Form Builder includes built-in CAPTCHA protection that can help reduce spam submissions.

All CAPTCHA settings are configured through your Kirby configuration file:

{% code title="config.your-domain.com.php " %}

```php
return [

    'plain.formblock' => [
        'captcha' => [

            // choose one of these:
            // math | hcaptcha | recaptcha_v2 | recaptcha_v3

            'mode' => 'math',

        ]
    ],

];
```

{% endcode %}

#### Available CAPTCHA Modes

**Math CAPTCHA (Default)**

The default option is a simple mathematical challenge that visitors must solve before submitting the form.

{% code title="config.your-domain.com.php " %}

```php
'plain.formblock' => [
    'captcha' => [
        'mode' => 'math',

        'math' => [
            'min' => 1,
            'max' => 90,
        ],
    ],
],
```

{% endcode %}

This option requires no external services and is usually sufficient for smaller websites.

**hCaptcha**

To use hCaptcha, configure your site key and secret key:

{% code title="config.your-domain.com.php " %}

```php
'plain.formblock' => [
    'captcha' => [
        'mode' => 'hcaptcha',

        'hcaptcha' => [
            'sitekey' => 'YOUR_SITE_KEY',
            'secret'  => 'YOUR_SECRET_KEY',
        ],
    ],
],
```

{% endcode %}

**Google reCAPTCHA v2**

{% code title="config.your-domain.com.php " %}

```php
'plain.formblock' => [
    'captcha' => [
        'mode' => 'recaptcha_v2',

        'recaptcha' => [
            'sitekey' => 'YOUR_SITE_KEY',
            'secret'  => 'YOUR_SECRET_KEY',
        ],
    ],
],
```

{% endcode %}

**Google reCAPTCHA v3**

{% code title="config.your-domain.com.php " %}

```php
'plain.formblock' => [
    'captcha' => [
        'mode' => 'recaptcha_v3',

        'recaptcha' => [
            'sitekey' => 'YOUR_SITE_KEY',
            'secret'  => 'YOUR_SECRET_KEY',

            'v3' => [
                'threshold' => 0.5,
                'action' => 'form_submit',
            ],
        ],
    ],
],
```

{% endcode %}

#### Which CAPTCHA Should I Choose?

**Math CAPTCHA**

* No third-party dependencies.
* Simple to configure.
* Default plugin option.

**hCaptcha**

* Privacy-friendly alternative.
* Good spam protection.
* Recommended if you want to avoid Google services.

**reCAPTCHA v2**

* Familiar "I'm not a robot" experience.
* Reliable bot protection.

**reCAPTCHA v3**

* Invisible to users.
* No interaction required.
* Best user experience, but requires Google services.

{% hint style="info" %}
For most Zero One websites, the default Math CAPTCHA is sufficient. If your website receives a large amount of spam, consider switching to hCaptcha or reCAPTCHA.
{% endhint %}

***

### Known Issue: Form Disappears After Submission

On some hosting environments, forms may disappear after submission.

This is typically caused by hosting providers that do not allow symbolic links, which are used by the plugin's dynamic validation system. 

To disable dynamic validation:

{% code title="config.your-domain.com.php " %}

```php
return [

    'plain.formblock' => [
        'dynamic_validation' => false,
    ],

];
```

{% endcode %}

We recommend adding this option using your [Multi-environment Configuration setup](/guide/installation/config-options.md#multi-environment-setup-recommended). 

***

### Recommended Configuration

For most websites, we recommend:

* Configuring SMTP before launching.
* Customizing the sender email address.
* Testing all forms after deployment.
* Keeping dynamic validation enabled unless your hosting environment causes issues.
* Exporting submissions periodically if they are business-critical.

***

### Need More Customization?

Form Builder can be extended with custom field types, templates, validation rules, translations, and hooks.

Advanced users should refer to the [official Form Block Suite documentation](https://github.com/plain-solutions-gmbh/kirby-form-block-suite) for detailed customization examples.