I'm developing a custom module which contains a form submission. I would like to add a captcha to it. And we want to use the Magento default captcha library so that the captcha is consistent with the one in registration form.


You need follow some step for using magento captcha into custom module.

Step 1 : Vendor/Module/etc/config.xml

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Store:etc/config.xsd">
        <captcha translate="label">
                        <label>Custom Form</label>

Step 2: Goto 'Admin -> Stores -> Configuration -> Customer -> Customer Configuration -> Captcha' and configure. You can able to see new forms value 'Custom Form'

Step 3: Create Vendor/Module/view/frontend/layout/yourroutid_index_index.xml

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" layout="1column" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
        <title>Custom Form</title>
        <referenceContainer name="content">
            <block class="Vendor\Module\Block\CaptchaForm" name="contactForm" template="Vendor_Module::captchaform.phtml">
                <container name="form.additional.info" label="Form Additional Info">
                    <block class="Magento\Captcha\Block\Captcha" name="captcha" after="-" cacheable="false">
                        <action method="setFormId">
                            <argument name="formId" xsi:type="string">custom_form</argument>
                        <action method="setImgWidth">
                            <argument name="width" xsi:type="string">230</argument>
                        <action method="setImgHeight">
                            <argument name="width" xsi:type="string">50</argument>
        <referenceBlock name="head.components">
            <block class="Magento\Framework\View\Element\Js\Components" name="captcha_page_head_components" template="Magento_Captcha::js/components.phtml"/>

Step 4: Vendor/Module/Block/CaptchaForm.php

namespace Vendor\Module\Block;

class CaptchaForm extends \Magento\Framework\View\Element\Template
    public function getFormAction()
        return $this->getUrl('yourroute/index/post', ['_secure' => true]);

Step 5: Vendor/Moduel/view/frontend/templates/captchaform.phtml

<form class="form contact"
      action="<?php /* @escapeNotVerified */ echo $block->getFormAction(); ?>"
      data-hasrequired="<?php /* @escapeNotVerified */ echo __('* Required Fields') ?>"
    <fieldset class="fieldset">
        <legend class="legend"><span><?php /* @escapeNotVerified */ echo __('Write Us') ?></span></legend><br />

        <div class="field name required">
            <label class="label" for="name"><span><?php /* @escapeNotVerified */ echo __('Name') ?></span></label>
            <div class="control">
                <input name="name" id="name" title="<?php /* @escapeNotVerified */ echo __('Name') ?>" value="" class="input-text" type="text" data-validate="{required:true}"/>
        <div class="field email required">
            <label class="label" for="email"><span><?php /* @escapeNotVerified */ echo __('Email') ?></span></label>
            <div class="control">
                <input name="email" id="email" title="<?php /* @escapeNotVerified */ echo __('Email') ?>" value="" class="input-text" type="email" data-validate="{required:true, 'validate-email':true}"/>
        <?php echo $block->getChildHtml('form.additional.info'); ?>
    <div class="actions-toolbar">
        <div class="primary">
            <input type="hidden" name="hideit" id="hideit" value="" />
            <button type="submit" title="<?php /* @escapeNotVerified */ echo __('Submit') ?>" class="action submit primary">
                <span><?php /* @escapeNotVerified */ echo __('Submit') ?></span>

Now you can able to see captcha into your form. Now need to validation your captcha using observer. So I use post controller predispatch event for validation.

Step 6: Vendor/Module/etc/frontend/events.xml

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Event/etc/events.xsd">
    <event name="controller_action_predispatch_yourroute_index_post">
        <observer name="captcha_custom_form" instance="Vendor\Module\Observer\CheckCustomFormObserver" />

Step 7: Vendor/Module/Observer/CheckCustomFormObserver.php

namespace Vendor\Module\Observer;

use Magento\Framework\Event\ObserverInterface;
use Magento\Framework\App\Request\DataPersistorInterface;
use Magento\Framework\App\ObjectManager;
use Magento\Captcha\Observer\CaptchaStringResolver;

class CheckCustomFormObserver implements ObserverInterface
     * @var \Magento\Captcha\Helper\Data
    protected $_helper;

     * @var \Magento\Framework\App\ActionFlag
    protected $_actionFlag;

     * @var \Magento\Framework\Message\ManagerInterface
    protected $messageManager;

     * @var \Magento\Framework\App\Response\RedirectInterface
    protected $redirect;

     * @var CaptchaStringResolver
    protected $captchaStringResolver;

     * @var DataPersistorInterface
    private $dataPersistor;

     * @param \Magento\Captcha\Helper\Data $helper
     * @param \Magento\Framework\App\ActionFlag $actionFlag
     * @param \Magento\Framework\Message\ManagerInterface $messageManager
     * @param \Magento\Framework\App\Response\RedirectInterface $redirect
     * @param CaptchaStringResolver $captchaStringResolver
    public function __construct(
        \Magento\Captcha\Helper\Data $helper,
        \Magento\Framework\App\ActionFlag $actionFlag,
        \Magento\Framework\Message\ManagerInterface $messageManager,
        \Magento\Framework\App\Response\RedirectInterface $redirect,
        CaptchaStringResolver $captchaStringResolver
    ) {
        $this->_helper = $helper;
        $this->_actionFlag = $actionFlag;
        $this->messageManager = $messageManager;
        $this->redirect = $redirect;
        $this->captchaStringResolver = $captchaStringResolver;

     * Check CAPTCHA on Custom Form
     * @param \Magento\Framework\Event\Observer $observer
     * @return void
    public function execute(\Magento\Framework\Event\Observer $observer)
        $formId = 'custom_form';
        $captcha = $this->_helper->getCaptcha($formId);
        if ($captcha->isRequired()) {
            /** @var \Magento\Framework\App\Action\Action $controller */
            $controller = $observer->getControllerAction();
            if (!$captcha->isCorrect($this->captchaStringResolver->resolve($controller->getRequest(), $formId))) {
                $this->messageManager->addError(__('Incorrect CAPTCHA.'));
                $this->getDataPersistor()->set($formId, $controller->getRequest()->getPostValue());
                $this->_actionFlag->set('', \Magento\Framework\App\Action\Action::FLAG_NO_DISPATCH, true);
                $this->redirect->redirect($controller->getResponse(), 'yourroute/index/index');

     * Get Data Persistor
     * @return DataPersistorInterface
    private function getDataPersistor()
        if ($this->dataPersistor === null) {
            $this->dataPersistor = ObjectManager::getInstance()

        return $this->dataPersistor;
  • Very detailed. I will try it out. – Paul Sep 5 '16 at 15:53
  • @Sohel Rana how can be add it into product review form – supriya mishra Jan 12 '17 at 5:57
  • @supriyamishra need to check – Sohel Rana Jan 12 '17 at 6:19
  • 1
    Hi The captcha is displayed but the observer controller_action_predispatch_** is i think not working as this captcha is not being validated – AbdulBasit Feb 20 '18 at 12:06
  • 1
    I resolved above error but i can't see the captcha in my custom form – jafar pinjar Aug 22 '18 at 6:59

Your Answer

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.

Not the answer you're looking for? Browse other questions tagged or ask your own question.