[austincalvelage]

Description

https://swingset-wox26j1v3.clerkstage.dev/components/captcha

Adds Captcha, the element clerk-js renders Cloudflare Turnstile into when a sign-in or sign-up requires a CAPTCHA. Mosaic's sign-in, sign-up and waitlist need it so that an interactive challenge has somewhere to show; without the element, clerk-js falls back to an invisible widget.

• Renders an empty div#clerk-captcha (CAPTCHA_ELEMENT_ID) with the .cl-captcha slot class. theme, size and language become the data-cl-theme, data-cl-size and data-cl-language attributes clerk-js passes to Turnstile, with the types of appearance.captcha.
• It takes no style and no children, so React leaves the inline styles and data-cl-interactive that clerk-js sets during a challenge alone. Legacy's CaptchaElement needs a MutationObserver for this.
• Without a theme, it matches the color-scheme it renders in: dark, light (also when none is set, since Mosaic renders light there), or auto for light dark. Legacy always uses auto, which follows the visitor's OS rather than the surrounding components.
• The Swingset page's playground stands in for clerk-js: it loads Turnstile with Cloudflare's test sitekey that always asks for an interactive challenge, renders it into Captcha and expands it the way clerk-js does.

The sign-in identifier step uses it in #10792, which stacks on this.

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated
clerk-js-sandbox	Ready	Preview	Nov 12, 2026 9:23pm UTC
swingset	Ready	Preview	Nov 12, 2026 9:23pm UTC

[changeset-bot]

🦋 Changeset detected

Latest commit: e678480

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

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

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

[coderabbitai]

No actionable comments were generated in the recent review.

Walkthrough

Adds the exported Captcha component with theme, size, and language props. When no theme is supplied, the component selects a theme from the computed color scheme. Tests cover rendering and theme selection. A Turnstile test hook, playground story, documentation, and registry entries are also added. The changeset file contains empty frontmatter and no release notes.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• clerk/javascript#10383: Its container resolver reads the #clerk-captcha element and the theme, language, and size attributes added by this PR.

Suggested reviewers: alexcarpenter, ephem

Merge Risk: Minimal · up to e6784

This change adds a new Captcha element with a playground story and documentation. No actionable merge-blocking risk was identified.

Pre-merge checks: 4

Check name	Status	Explanation
Title check		The title names the main change: adding a new Mosaic Captcha element for clerk-js Turnstile. The changeset adds the exported Captcha component and CaptchaProps, the styles, the tests, and the Swingset…
Description check		The description is directly related to the changeset. It explains the new Captcha element, its rendered div with CAPTCHA_ELEMENT_ID, the theme, size, and language data attributes, the color-scheme bas…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Title check

Explanation

The title names the main change: adding a new Mosaic Captcha element for clerk-js Turnstile. The changeset adds the exported Captcha component and CaptchaProps, the styles, the tests, and the Swingset story. The title is concise, specific, and follows conventional commit form.

Full details: Description check

Explanation

The description is directly related to the changeset. It explains the new Captcha element, its rendered div with CAPTCHA_ELEMENT_ID, the theme, size, and language data attributes, the color-scheme based theme derivation, and the Swingset playground page. It also states the purpose for Mosaic sign-in, sign-up, and waitlist flows.

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Linked repositories: Some configured repositories could not be included in this review. Cross-repository analysis may be incomplete. Please check linked-repository access and settings.

Recent review info

Run configuration

• Source mode: Auto
• Repository: clerk/javascript
• Branch: austin/mosaic-captcha
• File: .coderabbit.yaml
• Commit: e678480
• Layers: Repository YAML (base), Organization UI (inherited)
• Review profile: ASSERTIVE
• Plan: Team
• Run ID: 2a406eb6-2465-460d-a678-18d33c22a23f

Commits

Reviewing files that changed from the base of the PR and between 7d17759 and e678480.

Files selected for processing: 1

• packages/mosaic/src/components/captcha/captcha.tsx

Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• clerk/clerk_go (manual)
• clerk/dashboard (manual)
• clerk/accounts (manual)
• clerk/backoffice (manual)
• clerk/clerk (manual)
• clerk/clerk-docs (manual)
• clerk/cloudflare-workers (manual)
• clerk/internal-mobile-e2e (auto-detected)
• clerk/clerk-ios (auto-detected)
• clerk/clerk-android (auto-detected)

Included review availability: This review used your included allowance. 6 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 8 reviews per hour.

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@10796

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@10796

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@10796

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@10796

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@10796

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@10796

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@10796

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@10796

@clerk/expo-biometrics

npm i https://pkg.pr.new/@clerk/expo-biometrics@10796

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@10796

@clerk/expo-native-components

npm i https://pkg.pr.new/@clerk/expo-native-components@10796

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@10796

@clerk/express

npm i https://pkg.pr.new/@clerk/express@10796

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@10796

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@10796

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@10796

@clerk/mosaic

npm i https://pkg.pr.new/@clerk/mosaic@10796

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@10796

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@10796

@clerk/react

npm i https://pkg.pr.new/@clerk/react@10796

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@10796

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@10796

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@10796

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@10796

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@10796

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@10796

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@10796

commit: e678480

[blacksmith-sh]

Turnstile challenge shows in Captcha

Turnstile's interactive challenge showed inside the Captcha element, light in light mode and dark after toggling Dark mode, and clicking it solved.

Watch full video · Original footage · 0:00 Open the Captcha playground · 0:05 Switch Swingset to dark mode · 0:11 Solve the challenge

Also checked · 2 match

Theme follows color-scheme
Collapsed until interactive

_{Proof on e6784808 (from 7d17759d) · mocked: @clerk/clerk-js (Swingset's playground (test-turnstile.ts) renders Turnstile into Captcha the way...) · Did Proof get it right? Yes · No}

View full Proof report · React 👎 or comment @codesmith dismiss this proof to dismiss