Back to all lessons
Lesson library

Add a reCAPTCHA field

Add a reCAPTCHA field to forms and make sure your submissions are submitted by humans.

This video features an old UI. Updated version coming soon!

reCAPTCHA is a free service from Google that can help protect form submissions from spam and abuse. The service aims to ensure that your site's forms are only submitted by real users.

In this lesson
  1. Adding reCAPTCHA to forms
  2. Enabling reCAPTCHA validation for a project
  3. Testing functionality
  4. Customizing your reCAPTCHA
Before you get started
reCAPTCHA is a form element. Learn about Webflow forms.
reCAPTCHA will not function when you've set a custom form action to collect your form submissions.
Webflow forms including reCAPTCHA won't function on exported sites. If you intend to export your site, you'll need to integrate reCAPTCHA in your forms following Google's reCAPTCHA guide. Also, check out how to collect form submissions on exported sites.

Adding reCAPTCHA to forms

You can add reCAPTCHA to your forms from the add panel → elements→ forms section.


Simply drag a reCAPTCHA element into your form block.

reCAPTCHA will not display on the published site until you enable validation in project settings. Learn more below.
Good to know
reCAPTCHA auto-detects the site visitor's language and displays the widget in that language.

Enabling reCAPTCHA validation for a project

To use reCAPTCHA in a project, you need to set up reCAPTCHA for the published site. To do that:

  1. Register your site and generate API keys
  2. Enable reCAPTCHA validation

Register your site and generate API keys

Head over to Google’s reCAPTCHA page and choose the type of reCAPTCHA: reCAPTCHA v2: Checkbox.

choose the type of reCAPTCHA: reCAPTCHA v2: Checkbox

Then, register all domains associated with your site (see the note below). Once you register, you'll see two API keys in your reCAPTCHA setting. You'll be using these when enabling validation in the next step.

You’ll want to add any custom domains you’re using, such as You can also include (replacing example with your subdomain) if you’re using it for publication, staging, or testing. Subdomains for a custom domain are automatically registered. This means registration for also registers  Learn more about Google reCAPTCHA's domain name validation.
Registering domains may take up to 30 minutes to take effect.

Enable reCAPTCHA validation

Now, head over to project settings → forms tab → reCAPTCHA validation section and follow the steps below to enable reCAPTCHA on this project.

IMPORTANT — before enabling reCAPTCHA on your project
Enabling reCAPTCHA will enforce validation for all forms on this site. Any forms that do not have a reCAPTCHA element will fail to submit. This change will go into effect immediately as you click save (step 3 below), whether you republish your site or not. So, before you enable reCAPTCHA, make sure to add a reCAPTCHA element to each of your forms.

  1. Paste the API keys — the site key and the secret key — into the correct fields
  2. Enable reCAPTCHA validation
  3. Save your changes
  4. Publish your project
For security and correct functionality, make sure not to paste the secret key in the site key field.
If you prefer to keep designing, or you’re not ready to enable reCAPTCHA for all forms on your published site, you can come back to project settings to enable it later.

Testing functionality

On your published site, check to make sure the form works correctly.



reCAPTCHA may not function correctly for one of many reasons. Here are some issues, warnings, error messages, and how you can fix them.

You can't see the reCAPTCHA element on your published site 

Make sure you've enabled reCAPTCHA validation.

Error: Invalid site key — or — ERROR for site owner: Invalid site key

This warning appears when one or both API keys are incorrect in your project settings. To fix the issue:

  1. Head to your reCAPTCHA settings page
  2. Paste the API keys again in the correct fields in the project settings → forms tab → reCAPTCHA validation section
  3. Save the settings
  4. Publish your site
  5. Clear your cache and test again
ERROR for site owner: Invalid domain for site key

This warning indicates that you haven't registered the correct domain(s) for these reCAPTCHA keys. It also shows when you've removed the domain(s) registered for this reCAPTCHA.

reCAPTCHA warning: ERROR for site owner: Invalid domain for site key
The "ERROR for site owner: Invalid domain for site key" warning indicates that the domain you're testing the form on is not registered for the API keys you've set in this project's settings

To fix this error, add your domain(s) in your reCAPTCHA settings page, save the settings, and publish your site. Clear the cache and test again.

Pro tip
If clearing the cache doesn't work, test in an incognito window. One, you'll see if the error is fixed. Two, this will reset the cache for the reCAPTCHA setting, and now, you should be able to see the reCAPTCHA functioning correctly in all browsing windows.
If the key still doesn't work, delete the keys and generate new ones. Make sure to replace both keys in your project settings when you generate new keys. Note that the site key and secret key are case-sensitive.

Customizing your reCAPTCHA

reCAPTCHA has limited styling capabilities. However, you can use custom attributes to customize the reCAPTCHA element.

The default reCAPTCHA element
The default reCAPTCHA element
Custom attributes will only appear on the published site.

Change the color theme of the reCAPTCHA

By default, the reCAPTCHA element has the light theme. You can switch it to a dark theme.

A reCAPTCHA element with the dark theme
A reCAPTCHA element with the dark theme

To use the dark theme, add the following custom attribute:

  • Name: data-theme
  • Value: dark
To use the dark theme, add the following custom attribute:  Name: data-theme - Value: dark

Change size of the reCAPTCHA

The default size of the reCAPTCHA element is normal. You can use the compact size by adding a custom attribute.

A compact reCAPTCHA element
A compact reCAPTCHA element

To change the size of your reCAPTCHA element, add the following custom attribute:

  • Name: data-size
  • Value: compact
To change the size of your reCAPTCHA element, add the following custom attribute:  Name: data-size - Value: compact
Try Webflow — it's free