Contao Summit 2026 in Leipzig 15th and 16th October

validateFormField

The validateFormField hook is triggered when a form field is submitted. It passes the widget object and the form ID as arguments and expects a widget object as return value.

Parameters

  1. \Contao\Widget $widget

    Object of the current front end widget. Use it to access form field properties.

  2. string $formId

    Alias of the current form with the prefix auto_. Don’t confuse with $form->id.

  3. array $formData

    Form configuration data from the tl_form table.

  4. \Contao\Form $form

    The form instance.

Return Value

Return the $widget instance after modification or your custom widget.

Example

// src/EventListener/ValidateFormFieldListener.php
namespace App\EventListener;

use Contao\CoreBundle\DependencyInjection\Attribute\AsHook;
use Contao\Form;
use Contao\Widget;

#[AsHook('validateFormField')]
class ValidateFormFieldListener
{
    public function __invoke(Widget $widget, string $formId, array $formData, Form $form): Widget
    {
        if ('myform' === $form->formID && 'mywidget' === $widget->name) {
            // Do your custom validation and add an error if widget does not validate
            // …

            $widget->addError('My custom widget error');
        }

        return $widget;
    }
}

References