feat(core): enable recaptcha in forms by jamesqquick · Pull Request #2896 · bigcommerce/catalyst

jamesqquick · 2026-02-20T19:01:45Z

What/Why?

Match functionality of Stencil with regards to reCAPTCHA. Catalyst should respect the reCAPTCHA settings from the Control Panel and apply reCAPTCHA to forms appropriately based on those settings.

Forms that should support reCAPTCHA if enabled include:

product reviews
user registration
contact

Testing

with reCAPTCHA enabled in the Control Panel

Register & contact

Submit without completing the reCAPTCHA checkbox → submission is blocked and “Please complete the reCAPTCHA verification.” is shown.
Complete reCAPTCHA and submit with valid data → form submits and succeeds as expected.

Product review

Open “Write a review” and submit without completing reCAPTCHA → same error, no submit.
Complete reCAPTCHA and submit → review submits and success toast appears.

without reCAPTCHA enabled in the Control Panel

When reCAPTCHA is disabled in the control panel, all three forms submit without a reCAPTCHA widget or “complete reCAPTCHA” errors.

Migration

changeset-bot · 2026-02-20T19:01:50Z

🦋 Changeset detected

Latest commit: 901b3c8

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@bigcommerce/catalyst-core	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-02-20T19:01:51Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
catalyst	Ready	Preview, Comment	Mar 13, 2026 8:20pm

matthewvolk

High level, I think this is pretty good - the main "architectural" feedback I have is that it looks like you introduce two ways to get the recaptcha key but are only using one of them... wondering if that's redundant. I could be misunderstanding intent here, so I definitely encourage a second reviewer to weigh in!

Outside of this, my only other concern is the library is a bit old... not sure if it's being maintained, especially looking at some of the recent issues: dozoisch/react-google-recaptcha#301

core/vibes/soul/form/dynamic-form/index.tsx

core/components/recaptcha-provider/index.tsx

github-actions · 2026-03-03T21:18:09Z

Bundle Size Report

Comparing against baseline from 00496f5 (2026-03-13).

Metric	Baseline	Current	Delta
Total JS	422.9 kB	429.7 kB	+6.8 kB (+1.6%)

Per-Route First Load JS

Route	Baseline	Current	Delta
/(default)/(auth)/change-password/page	300.8 kB	301.2 kB	+0.4 kB (+0.1%)
/(default)/(auth)/login/forgot-password/page	299.9 kB	300.4 kB	+0.5 kB (+0.2%)
/(default)/(auth)/login/page	300.4 kB	300.8 kB	+0.4 kB (+0.1%)
/(default)/(auth)/register/page	333.3 kB	336.9 kB	+3.6 kB (+1.1%)
/(default)/(faceted)/brand/[slug]/page	312.4 kB	312.9 kB	+0.5 kB (+0.2%)
/(default)/(faceted)/category/[slug]/page	320.8 kB	321.2 kB	+0.4 kB (+0.1%)
/(default)/(faceted)/search/page	312.4 kB	312.9 kB	+0.5 kB (+0.2%)
/(default)/[...rest]/page	295.4 kB	295.9 kB	+0.5 kB (+0.2%)
/(default)/account/addresses/page	336.8 kB	340.4 kB	+3.6 kB (+1.1%)
/(default)/account/orders/[id]/page	303.6 kB	304 kB	+0.4 kB (+0.1%)
/(default)/account/orders/page	304.5 kB	305 kB	+0.5 kB (+0.2%)
/(default)/account/settings/page	311.2 kB	311.6 kB	+0.4 kB (+0.1%)
/(default)/account/wishlists/[id]/page	318.6 kB	319 kB	+0.4 kB (+0.1%)
/(default)/account/wishlists/page	313.6 kB	314 kB	+0.4 kB (+0.1%)
/(default)/blog/[blogId]/page	295.4 kB	295.9 kB	+0.5 kB (+0.2%)
/(default)/blog/page	296.4 kB	296.9 kB	+0.5 kB (+0.2%)
/(default)/cart/page	316.3 kB	316.8 kB	+0.5 kB (+0.2%)
/(default)/compare/page	307.6 kB	308.1 kB	+0.5 kB (+0.2%)
/(default)/gift-certificates/balance/page	299.4 kB	299.8 kB	+0.4 kB (+0.1%)
/(default)/gift-certificates/page	295.4 kB	295.9 kB	+0.5 kB (+0.2%)
/(default)/gift-certificates/purchase/page	335.8 kB	339.4 kB	+3.6 kB (+1.1%)
/(default)/page	312.6 kB	313.1 kB	+0.5 kB (+0.2%)
/(default)/product/[slug]/page	364.3 kB	367.9 kB	+3.6 kB (+1%)
/(default)/webpages/[id]/contact/page	334.2 kB	337.8 kB	+3.6 kB (+1.1%)
/(default)/webpages/[id]/normal/page	303.6 kB	304 kB	+0.4 kB (+0.1%)
/(default)/wishlist/[token]/page	308.5 kB	308.9 kB	+0.4 kB (+0.1%)

Threshold: 5% increase. Routes with ⚠️ exceed the threshold.

jorgemoya · 2026-03-06T23:21:34Z

core/vibes/soul/sections/reviews/review-form.tsx

+        const token = recaptchaRef.current.getValue();
+
+        if (!token || typeof token !== 'string') {
+          setRecaptchaError(t('recaptchaRequired'));


Is there no way to validate for recaptcha within the form action? And return the errors accordingly? 🤔

Good call. Refactored to move that logic to the server and create utility functions to parse and validate the token.

Even with the refactor this is still present. I think we can remove all client facing logic for showing the errors and validating.

Got it. Removed all client logic in lieu of leveraging logic on the server

jorgemoya

Thanks for looking into validating and erroring from the actions, but I still see some leftover logic from the previous implementation. Should be easy to clean up, I believe.

Another question, should we include reCaptcha in other pages? Login, reset password? I forget if once we enable reCaptcha on a storefront, forms automatically require a token to succeed?

Another detail missing is how to make sure the forms still succeed in our e2e tests when reCaptcha is enabled. Our old approach was to use the X-Vercel-Set-Bypass-Cookie: true, however another approach is to make sure the E2E test store has Google's test key 🤔? This would work now since our E2E test store is separate from our demo sites.

jorgemoya · 2026-03-11T21:37:04Z

core/lib/recaptcha.ts

+          failedLoginLockoutDurationSeconds
+          isEnabledOnCheckout


I don't think these two are being used. Can we use it for something here? I would remove if not needed.

Great catch. Removed.

jorgemoya · 2026-03-11T21:39:41Z

core/lib/recaptcha.ts

+  return { siteKey, token };
+}
+
+export function validateRecaptchaToken(


Maybe change to assertRecaptchaTokenPresent since it's not really validating anything (this happens server side)?

jorgemoya · 2026-03-11T21:40:56Z

core/vibes/soul/form/dynamic-form/index.tsx

+      setRecaptchaError(null);
+
+      let payload: FormData = formData;
+
+      if (recaptchaSiteKey && recaptchaRef.current) {
+        const token = recaptchaRef.current.getValue();
+
+        if (!token || typeof token !== 'string') {
+          setRecaptchaError(t('recaptchaRequired'));
+
+          return;
+        }
+
+        payload = new FormData(event.currentTarget);
+        payload.set(RECAPTCHA_TOKEN_FORM_KEY, token);
+        recaptchaRef.current.reset();
+      }


The cool thing about validating on the server is that we no longer need this.

Removed. Great call.

jorgemoya · 2026-03-11T21:41:07Z

core/vibes/soul/form/dynamic-form/index.tsx

              {submitLabel}
            </SubmitButton>
          </div>
+          {recaptchaError ? <FormStatus type="error">{recaptchaError}</FormStatus> : null}


No longer needed too.

jorgemoya · 2026-03-11T21:41:40Z

core/vibes/soul/form/dynamic-form/index.tsx

+export function DynamicForm<F extends Field>(props: DynamicFormProps<F>) {
+  return <DynamicFormInner {...props} />;
+}


Why did we add this Inner component? 🤔

jorgemoya · 2026-03-11T21:42:28Z

core/vibes/soul/sections/reviews/review-form.tsx

+        const token = recaptchaRef.current.getValue();
+
+        if (!token || typeof token !== 'string') {
+          setRecaptchaError(t('recaptchaRequired'));


Even with the refactor this is still present. I think we can remove all client facing logic for showing the errors and validating.

Made-with: Cursor

…ut from getReCaptchaSettings Made-with: Cursor

jamesqquick · 2026-03-12T19:59:44Z

Thanks for looking into validating and erroring from the actions, but I still see some leftover logic from the previous implementation. Should be easy to clean up, I believe.

Another question, should we include reCaptcha in other pages? Login, reset password? I forget if once we enable reCaptcha on a storefront, forms automatically require a token to succeed?

Another detail missing is how to make sure the forms still succeed in our e2e tests when reCaptcha is enabled. Our old approach was to use the X-Vercel-Set-Bypass-Cookie: true, however another approach is to make sure the E2E test store has Google's test key 🤔? This would work now since our E2E test store is separate from our demo sites.

I'm not sure what we want to do for forms on other pages. I started with mirroring the Stencil functionality which is specific to these forms and not all of them.

vercel bot had a problem deploying to Preview February 20, 2026 19:03 Failure

vercel bot had a problem deploying to Preview February 23, 2026 17:46 Failure

vercel bot had a problem deploying to Preview February 23, 2026 18:00 Failure

matthewvolk reviewed Feb 27, 2026

View reviewed changes

core/vibes/soul/form/dynamic-form/index.tsx Outdated Show resolved Hide resolved

core/components/recaptcha-provider/index.tsx Outdated Show resolved Hide resolved

vercel bot had a problem deploying to Preview February 27, 2026 21:33 Failure

vercel bot had a problem deploying to Preview March 2, 2026 17:33 Failure

jamesqquick force-pushed the recaptch branch from 15d11d2 to 363f142 Compare March 2, 2026 17:35

vercel bot had a problem deploying to Preview March 2, 2026 17:37 Failure

jamesqquick requested a review from matthewvolk March 2, 2026 17:40

vercel bot had a problem deploying to Preview March 3, 2026 20:53 Failure

vercel bot deployed to Preview March 3, 2026 21:18 View deployment

vercel bot deployed to Preview March 3, 2026 21:28 View deployment

vercel bot deployed to Preview March 4, 2026 01:26 View deployment

jamesqquick marked this pull request as ready for review March 5, 2026 21:23

jamesqquick requested a review from a team as a code owner March 5, 2026 21:23

jorgemoya reviewed Mar 6, 2026

View reviewed changes

vercel bot deployed to Preview March 9, 2026 17:10 View deployment

vercel bot deployed to Preview March 9, 2026 17:47 View deployment

jamesqquick requested a review from jorgemoya March 9, 2026 18:02

jorgemoya reviewed Mar 11, 2026

View reviewed changes

jamesqquick requested a review from a team as a code owner March 12, 2026 16:18

vercel bot had a problem deploying to Preview March 12, 2026 16:20 Failure

jamesqquick added 5 commits March 12, 2026 11:20

added recaptcha v3

9b40f6d

update recaptcha package and make visible on forms

12c8787

linting

6fd579b

make recaptcha optional for dynamic-form

27fa4a0

remove comments

58ff4c5

jamesqquick added 2 commits March 12, 2026 12:02

fix linting

4253cf2

remove client side logic and validation for recaptcha

c688abb

vercel bot deployed to Preview March 12, 2026 17:08 View deployment

remove unused properties from RecaptchaSettings interface

140d3a7

vercel bot deployed to Preview March 12, 2026 17:10 View deployment

remove unnecessary DynamicFormInner wrapper component

fe10cd2

Made-with: Cursor

vercel bot deployed to Preview March 12, 2026 17:13 View deployment

remove unused failedLoginLockoutDurationSeconds and isEnabledOnChecko…

5c2ef18

…ut from getReCaptchaSettings Made-with: Cursor

vercel bot deployed to Preview March 12, 2026 19:44 View deployment

jamesqquick requested a review from jorgemoya March 12, 2026 19:58

add changeset

14f2cbe

vercel bot deployed to Preview March 12, 2026 20:10 View deployment

Merge branch 'canary' into recaptch

dd6357a

vercel bot deployed to Preview March 13, 2026 16:59 View deployment

jamesqquick changed the title ~~Recaptcha~~ feat(core): enable recaptcha in forms Mar 13, 2026

chore: add tests for recaptcha

cfe8a7f

vercel bot deployed to Preview March 13, 2026 19:45 View deployment

jorgemoya approved these changes Mar 13, 2026

View reviewed changes

Merge branch 'canary' into recaptch

901b3c8

vercel bot deployed to Preview March 13, 2026 20:20 View deployment

matthewvolk approved these changes Mar 13, 2026

View reviewed changes

jamesqquick added this pull request to the merge queue Mar 13, 2026

Merged via the queue into canary with commit fc84210 Mar 13, 2026
17 of 18 checks passed

jamesqquick deleted the recaptch branch March 13, 2026 22:49

github-actions bot mentioned this pull request Mar 13, 2026

Version Packages (canary) #2924

Closed

jorgemoya mentioned this pull request Mar 16, 2026

sync integrations/makeswift with canary #2926

Merged

github-actions bot mentioned this pull request Mar 16, 2026

Version Packages (canary) #2927

Merged

jorgemoya mentioned this pull request Mar 16, 2026

sync integrations/makeswift with canary #2928

Merged

Conversation

jamesqquick commented Feb 20, 2026 • edited by atlassian bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What/Why?

Testing

with reCAPTCHA enabled in the Control Panel

without reCAPTCHA enabled in the Control Panel

Migration

Uh oh!

changeset-bot bot commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

matthewvolk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle Size Report

Per-Route First Load JS

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jorgemoya left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jamesqquick commented Mar 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jamesqquick commented Feb 20, 2026 •

edited by atlassian bot

Loading

changeset-bot bot commented Feb 20, 2026 •

edited

Loading

vercel bot commented Feb 20, 2026 •

edited

Loading

github-actions bot commented Mar 3, 2026 •

edited

Loading