Skip to content
Rack Middleware for CAPTCHA verification via Recaptcha API
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Build Status

Drop this Rack middleware in your web application to enable CAPTCHA verification via Recaptcha API.

How to Use


First, install the library with: [sudo] gem install rack-recaptcha

You have to require 'rack-recaptcha' in your gemfile.

## Gemfile
gem 'rack-recaptcha', :require => 'rack/recaptcha'
Available options for `Rack::Recaptcha` middleware are:

* :public_key -- your ReCaptcha API public key *(required)*
* :private_key -- your ReCaptcha API private key *(required)*
* :proxy_host -- the HTTP Proxy hostname *(optional)*
* :proxy_port -- the HTTP Proxy port *(optional)*
* :proxy_user -- the HTTP Proxy user *(optional, omit unless the proxy requires it)*
* :proxy_password -- the HTTP Proxy password *(optional, omit unless the proxy requires it)*

Now configure your app to use the middleware. This might be different across each web framework.


## app.rb
use Rack::Recaptcha, :public_key => 'KEY', :private_key => 'SECRET'
helpers Rack::Recaptcha::Helpers


## app/app.rb
use Rack::Recaptcha, :public_key => 'KEY', :private_key => 'SECRET'
helpers Rack::Recaptcha::Helpers


## application.rb:
module YourRailsAppName
  class Application < Rails::Application
    config.gem 'rack-recaptcha', :lib => 'rack/recaptcha'
    config.middleware.use Rack::Recaptcha, :public_key => 'KEY', :private_key => 'SECRET'

## application_helper.rb or whatever helper you want it in.
module ApplicationHelper
  include Rack::Recaptcha::Helpers

## application_controller.rb or whatever controller you want it in.
class ApplicationController < ActionController::Base
  include Rack::Recaptcha::Helpers


The Rack::Recaptcha::Helpers module (for Sinatra, Rails, Padrino) adds these methods to your app:

Return a javascript recaptcha form

  recaptcha_tag :challenge

Return a non-javascript recaptcha form

  recaptcha_tag :noscript

Return a ajax recaptcha form

  recaptcha_tag :ajax

For ajax recaptcha's, you can pass additional options like:

  recaptcha_tag :ajax, :display => { :theme => 'red'}

For non-ajax recaptcha's, you can pass additional options like:

  # Overrides the key set in Middleware
  recaptcha_tag :challenge, :public_key => KEY

  # Adjust Height and/or Width
  recaptcha_tag :noscript, :height => 300, :width => 500

  # Adjust the rows and/or columns
  recaptcha_tag :challenge, :row => 3, :cols => 5

  # Set the language
  recaptcha_tag :noscript, :language => :en

To test whether or not the verification passed, you can use:


The recaptcha_valid? helper can also be overloaded during tests. You can set its response to either true or false by doing the following:

 # Have recaptcha_valid? return true

 # Or have it return false
 Rack::Recaptcha.test_mode! :return => false

For additional options and resources checkout the customization page


In Padrino, here's how you would use the helpers.

## new.haml
- form_tag '/login', :class => 'some_form', :method => 'post' do
  = text_field_tag :email
  = password_field_tag :password
  = recaptcha_tag(:challenge)
  = submit_tag "Submit"

## sessions.rb
post :create, :map => '/login' do
  if recaptcha_valid?

In rails, you'll need to use also use the raw method:

## new.html.haml
- form_tag '/login' do
  = raw recaptcha_tag(:challenge)
  = submit_tag "Submit"


Daniel Mendler - minad

  • support for multiple paths and helpers clean up

Eric Anderson - eric1234

  • Make verify independently usable.

Chad Johnston - iamthechad

  • Adding Error Message handling in recaptcha widget

Eric Hu - eric-hu

  • Patching error message issue when no request is present

Tobias Begalke - elcamino

  • Added HTTP Proxy support

Julik Tarkhanov - julik

  • Adding rack-recaptcha to travis-ci

Rob Worley - robworley

  • Adding language setting for recaptcha form

sam71 - sam71

  • Fix recaptcha hanging when used in proxy environment.

Note on Patches/Pull Requests

  • Fork the project.
  • Make your feature addition or bug fix.
  • Add tests for it. This is important so I don't break it in a future version unintentionally.
  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
  • Send me a pull request. Bonus points for topic branches.


Copyright (c) 2010, 2011, 2012 Arthur Chiu. See LICENSE for details.

You can’t perform that action at this time.