Created: 2008-04-11 23:01
Updated: 2019-02-28 11:35
License: mit


Author: Jason L Perry (
Copyright: Copyright (c) 2007-2013 Jason L Perry
License: MIT

This plugin adds helpers for the reCAPTCHA API. In your views you can use the recaptcha_tags method to embed the needed javascript, and you can validate in your controllers with verify_recaptcha or verify_recaptcha!, which throws an error on failiure.

Rails Installation

obtain a reCAPTCHA API key. Note: Use localhost or in domain if using localhost:3000.

gem "recaptcha"

Keep keys out of the code base with environment variables.
Set in production and locally use dotenv, make sure to add it above recaptcha.

Otherwise see Alternative API key setup.

export RECAPTCHA_SITE_KEY  = '6Lc6BAAAAAAAAChqRbQZcn_yyyyyyyyyyyyyyyyy'
export RECAPTCHA_SECRET_KEY = '6Lc6BAAAAAAAAKN3DRm6VA_xxxxxxxxxxxxxxxxx'

Add recaptcha_tags to the forms you want to protect.

<%= form_for @foo do |f| %>
  # ... other tags
  <%= recaptcha_tags %>
  # ... other tags
<% end %>

And, add verify_recaptcha logic to each form action that you've protected.

# app/controllers/users_controller.rb
@user =[:user].permit(:name))
if verify_recaptcha(model: @user) &&
  redirect_to @user
  render 'new'

Sinatra / Rack / Ruby installation

See sinatra demo for details.

  • add gem 'recaptcha' to Gemfile
  • set env variables
  • include Recaptcha::ClientHelper where you need recaptcha_tags
  • include Recaptcha::Verify where you need verify_recaptcha


Some of the options available:

Option Description
:noscript Include content (default true)
:theme Specify the theme to be used per the API. Available options: dark and light. (default light)
:ajax Render the dynamic AJAX captcha per the API. (default false)
:site_key Override site API key
:error Override the error code returned from the reCAPTCHA API (default nil)
:size Specify a size (default nil)
:hl Optional. Forces the widget to render in a specific language. Auto-detects the user's language if unspecified. (See language codes)
:onload Optional. The name of your callback function to be executed once all the dependencies have loaded. (See explicit rendering)
:render Optional. Whether to render the widget explicitly. Defaults to onload, which will render the widget in the first g-recaptcha tag it finds. (See explicit rendering)
:nonce Optional. Sets nonce attribute for script. Can be generated via SecureRandom.base64(32). (default nil)
:id Specify an html id attribute (default nil)
:script If you do not need to add a script tag by helper you can set the option to false. It's necessary when you add a script tag manualy (default true)
:callback Optional. Name of success callback function, executed when the user submits a successful response
:expired_callback Optional. Name of expiration callback function, executed when the reCAPTCHA response expires and the user needs to re-verify.
:error_callback Optional. Name of error callback function, executed when reCAPTCHA encounters an error (e.g. network connectivity)

You can also override the html attributes for the sizes of the generated textarea and iframe elements, if CSS isn't your thing. Inspect the source of recaptcha_tags to see these options.


This method returns true or false after processing the parameters from the reCAPTCHA widget. Why isn't this a model validation? Because that violates MVC. You can use it like this, or how ever you like. Passing in the ActiveRecord object is optional, if you do--and the captcha fails to verify--an error will be added to the object for you to use.

Some of the options available:

Option Description
:model Model to set errors.
:attribute Model attribute to receive errors. (default :base)
:message Custom error message.
:secret_key Override secret API key.
:timeout The number of seconds to wait for reCAPTCHA servers before give up. (default 3)
:response Custom response parameter. (default: params['g-recaptcha-response'])
:hostname Expected hostname or a callable that validates the hostname, see domain validation and hostname docs. (default: nil, but can be changed by setting config.hostname)
:env Current environment. The request to verify will be skipped if the environment is specified in configuration under skip_verify_env


Make sure to read Invisible reCAPTCHA.

With a single form on a page

  1. The invisible_recaptcha_tags generates a submit button for you.
<%= form_for @foo do |f| %>
  # ... other tags
  <%= invisible_recaptcha_tags text: 'Submit form' %>
<% end %>

Then, add verify_recaptcha to your controller as seen above.

With multiple forms on a page

  1. You will need a custom callback function, which is called after verification with Google's reCAPTCHA service. This callback function must submit the form. Optionally, invisible_recaptcha_tags currently implements a JS function called invisibleRecaptchaSubmit that is called when no callback is passed. Should you wish to override invisibleRecaptchaSubmit, you will need to use invisible_recaptcha_tags script: false, see lib/recaptcha/client_helper.rb for details.
  2. The invisible_recaptcha_tags generates a submit button for you.
<%= form_for @foo, html: {id: 'invisible-recaptcha-form'} do |f| %>
  # ... other tags
  <%= invisible_recaptcha_tags callback: 'submitInvisibleRecaptchaForm', text: 'Submit form' %>
<% end %>
// app/assets/javascripts/application.js
var submitInvisibleRecaptchaForm = function () {

Finally, add verify_recaptcha to your controller as seen above.

Programmatically invoke

  1. Specify ui option
<%= form_for @foo, html: {id: 'invisible-recaptcha-form'} do |f| %>
  # ... other tags
  <button type="button" id="submit-btn">
  <%= invisible_recaptcha_tags ui: :invisible, callback: 'submitInvisibleRecaptchaForm' %>
<% end %>
// app/assets/javascripts/application.js
document.getElementById('submit-btn').addEventListener('click', function (e) {
  // do some validation
  if(isValid) {
    // call reCAPTCHA check

var submitInvisibleRecaptchaForm = function () {

I18n support

reCAPTCHA passes two types of error explanation to a linked model. It will use the I18n gem to translate the default error message if I18n is available. To customize the messages to your locale, add these keys to your I18n backend:

recaptcha.errors.verification_failed error message displayed if the captcha words didn't match recaptcha.errors.recaptcha_unreachable displayed if a timeout error occured while attempting to verify the captcha

Also you can translate API response errors to human friendly by adding translations to the locale (config/locales/en.yml):

      verification_failed: 'Fail'


By default, reCAPTCHA is skipped in "test" and "cucumber" env. To enable it during test:


Alternative API key setup


# config/initializers/recaptcha.rb
Recaptcha.configure do |config|
  config.site_key  = '6Lc6BAAAAAAAAChqRbQZcn_yyyyyyyyyyyyyyyyy'
  config.secret_key = '6Lc6BAAAAAAAAKN3DRm6VA_xxxxxxxxxxxxxxxxx'
  # Uncomment the following line if you are using a proxy server:
  # config.proxy = ''


For temporary overwrites (not thread safe).

Recaptcha.with_configuration(site_key: '12345') do
  # Do stuff with the overwritten site_key.

Per call

Pass in keys as options at runtime, for code base with multiple reCAPTCHA setups:

recaptcha_tags site_key: '6Lc6BAAAAAAAAChqRbQZcn_yyyyyyyyyyyyyyyyy'

# and

verify_recaptcha secret_key: '6Lc6BAAAAAAAAKN3DRm6VA_xxxxxxxxxxxxxxxxx'


Cookies help us deliver our services. By using our services, you agree to our use of cookies Learn more