Recaptcha Element - #recaptcha{}


The recaptcha element produces a recaptcha element. For more information about recaptchas you may refer to

The element is rendered and evaluated by an external library.

The captcha is processed as follows:

  • The user solves the captcha.
  • If the solution is wrong the captcha gets refreshed until the user gives up or the solution is correct, and a Page:recaptcha_event is called with a Result of error.
  • If the solution is correct the Page:recaptcha_event callback is called with a Result of ok.
  • The return value of the Page:recaptcha_event callback is evaluated as follows:
  • If the value is ok nothing is done.
  • If the return value is error, the captcha gets refreshed.
  • If the return value is {error, Msg}, the captcha gets refreshed and the Msg is shown as the error message.


Before you can use the the recaptcha element, you have to register at

After that, you have to either specify the following values in your app.config or specify them as attributes to the #recaptcha{} element itself.

 {nitrogen, [
              [{public_key, "recaptcha_public_key"},
               {private_key, "recaptcha_private_key"},
               {challenge_url, ""},
               {verify_url, ""}]}


   #recaptcha {


The following attributes are required unless they are defined as nitrogen environment variables above.

  • public_key (string) - Public key provided by the Recaptcha service.
  • private_key (string) - Private key provided by the Recaptcha service.

The following attributes are optional

  • tag (term) - The "tag" for the recaptcha element to be passed to the recaptcha_event/2 function
  • button_id (atom) - The button's id
  • button_label (string) - The button's label
  • button_class (string, atom, or list of atoms) - The button's HTML class.
  • captcha_opts (proplist) - The captcha's options. For more information see the official Recaptcha Documentation custom_theme_widget is not supported
  • delegate (Module) :: The module where the event callback gets called
  • fail_body (List) :: The fail message. It can be a simple string or an array of Nitrogen elements. It will be displayed below the recaptcha if the user fails to enter the correct recaptcha.
  • challenge_url (string) - The challenge URL as specified in the Recaptcha Documentation (default:")
  • verify_url (string) - The verification URL as specified in the Recaptcha Documentation (default:")

Postback Function

When a recaptcha succeeds or fails, the recaptcha_event/2 function is called on your page module. Tag will be from the tag attribute above, and Result will be a status atom, either ok if successful, or {error, ErrorMessage} if the recaptcha fails.

recaptcha_event/2 can return any of the following:

  • ok - Everything is okay.
  • error - There was something that failed (maybe you did some data validation in the event_recaptcha/2 function and something failed so let's just return an error.
  • {error, ErrorMessage} - Something went wrong, and let's set the error message to the contents of ErrorMessage (which, like fail_body above, can be either text or Nitrogen elements).
recaptcha_event(_Tag, ok) ->
   wf:wire(#alert{text="Congrats, you're human"}),
recaptcha_event(_Tag, {error, ErrorReason}) ->
   wf:wire(#alert{text="WE THINK YOU'RE A ROBOT! YOU MUST PROVE OTHERWISE!"}),
   {error, "Please Try again!"}.

Regarding Validation with Recaptcha

If you wish to trigger validators before the Recaptcha gets used, you'll need to wire the validators to the Recaptcha's button_id attribute.

You can see this in use in the example below:


Code in a page module may look like this:

inner_body() ->
   %% Wire a validator to be triggered by `recaptcha_button`, and target `name`
   wf:wire(recaptcha_button, name, #validate{ validators=[
      #label{text="Enter your name"},

event_recaptcha(my_recaptcha, ok) ->
    case check_user_input() of
        ok     -> wf:remove(recaptcha),
        error  -> {error, "FAIL!"}

check_user_input() ->
%% your check routine

See Also

View Source or Submit Corrections for this Documentation Page
Copyright © 2008-2024 Nitrogen Web Framework. Released under the MIT License.