Use the shortcode when you need Turnstile on a form the plugin does not have a built-in toggle for — a custom MailChimp sign-up, a theme-built form, a page builder widget, etc.

Quick Use

Drop this in any page, post, widget, or template:

[wkcft-turnstile]

The widget renders with your current global settings (General + Design Studio).

Shortcode in CF7

For Contact Form 7 forms, use the dedicated variant:

[cf7-turnstile]

It hooks into CF7's validation API to block failed submissions correctly.

Attributes

All attributes override global defaults only for this shortcode instance.

Attribute	Values	Overrides
`theme`	`light` · `dark` · `auto`	Theme
`size`	`normal` · `compact` · `flexible`	Size
`language`	`en` · `fr` · `de` · `es` · `it` · `pt` · `ja` · `zh` · `ar` · `ru` · `hi` · `auto`	Language
`class`	any class names	Adds extra CSS classes
`id`	any string	Sets custom DOM id
`action`	any string	Passed to Cloudflare for analytics attribution
`appearance`	`always` · `interaction-only` · `execute`	Visibility mode

Examples

[wkcft-turnstile]

Dark, Compact, French

[wkcft-turnstile theme="dark" size="compact" language="fr"]

Invisible (Execute Mode)

Silent background verification — user sees nothing unless Cloudflare detects a bot.

[wkcft-turnstile appearance="execute"]

With Custom CSS Class for Styling

[wkcft-turnstile class="my-custom-widget newsletter-captcha"]

With Analytics Action Name

Lets you filter Turnstile's Cloudflare analytics by form.

[wkcft-turnstile action="newsletter-signup"]

Typical Placements

Inside a Post or Page

Just type the shortcode in the editor. Gutenberg renders a Shortcode block; Classic editor renders it inline.

Appearance → Widgets → Text widget → paste shortcode.

In a Theme Template File

Inside a PHP template:

<?php echo do_shortcode('[wkcft-turnstile]'); ?>

Inside a Form Plugin That Accepts Shortcodes

Most page builders (Elementor, Beaver Builder, Divi) have a Shortcode widget/module. Drop the shortcode there.

For form plugins that do NOT support shortcodes inside form fields, use the built-in handlers on the WooCommerce Forms tab instead.

Token Submission

For the widget to work on a custom form, the form must submit the Turnstile token to your server. The token is the value of an input named cf-turnstile-response.

When the shortcode renders, it adds this input automatically — it sits inside the widget wrapper. When the user completes the CAPTCHA, Cloudflare populates the input value. When the form posts, the token goes with it.

If your form uses AJAX, you need to grab the token manually:

const token = document.querySelector('input[name="cf-turnstile-response"]').value;
// then send `token` in your AJAX payload

Then validate server-side by calling WKCFT_Validator::wkcft_check($token, 'my-custom-form').

Full validation example: REST API.

Server-Side Validation for Custom Forms

If your form is handled by your own code:

if (isset($_POST['cf-turnstile-response'])) {
    $result = WKCFT_Validator::wkcft_instance()->wkcft_check(
        sanitize_text_field($_POST['cf-turnstile-response']),
        'my-custom-form'
    );
    
    if (!$result['success']) {
        wp_die('CAPTCHA failed: ' . esc_html($result['error-codes'][0] ?? 'unknown'));
    }
}

$result shape:

[
  'success' => true|false,
  'error-codes' => ['missing-input-response', ...]  // only on failure
]

Shortcode Rendered HTML

For reference, the shortcode outputs:

<div class="wkcft-turnstile wkcft-shortcode YOUR_CUSTOM_CLASS" id="YOUR_ID" style="WRAPPER_STYLE">
  <!-- optional label -->
  <div class="cf-turnstile"
       data-sitekey="..."
       data-theme="light"
       data-size="normal"
       data-language="auto"
       data-appearance="always"
       data-action="YOUR_ACTION">
  </div>
  <!-- optional helper text -->
</div>

Multiple Widgets Per Page

You can place multiple shortcodes on the same page. Each renders a fresh widget with its own token. IDs are auto-generated unique if you do not pass id.

Target .wkcft-turnstile in your theme CSS to tweak placement and spacing. Pass a class attribute in the shortcode to add a context-specific hook:

[wkcft-turnstile class="newsletter-captcha"]

Then in CSS:

.wkcft-turnstile.newsletter-captcha { margin-top: 16px; }

Troubleshooting

Problem	Fix
Shortcode outputs literal text `[wkcft-turnstile]`	Plugin not active, or context does not execute shortcodes (e.g., a plain text-only widget)
Widget renders but form submits without validation	Your form handler does not call `WKCFT_Validator::wkcft_check()` — add manual validation
"Invalid sitekey"	Domain not in your Cloudflare widget's hostname list
Shortcode inside a repeater field shows multiple "Invalid sitekey"	Known Cloudflare limitation — you need unique widget IDs. Use the `id` attribute: `[wkcft-turnstile id="widget-1"]`

Third-Party Form Plugins — Built-in handlers for CF7, WPForms, Gravity, etc.
General Settings — Global defaults this can override
Design Studio — Default styling
REST API — Programmatic token verification
Filters & Hooks — Customize widget classes + validation

Shortcode — Drop the Widget Anywhere