Widget options

Every option and data attribute of the Wicket widget with its values and default, the callbacks, the functions of window.wicket and the error codes.

View as Markdown

The widget takes the options Cloudflare Turnstile takes, with the same names and defaults, and a few of its own. Add Wicket to your site shows them in use.

Where an option goes

Section titled Where an option goes

As a data- attribute on the widget's container: the option's name after data-, such as data-theme="dark" or data-refresh-expired="manual".
As a key of the object you pass to wicket.render(container, options). Write a name that has hyphens in quotes ("refresh-expired"), or in camelCase (refreshExpired). An option in the object wins over the same data- attribute.

Invalid values

Section titled Invalid values

The script never stops for a bad option. It ignores the value, uses the default, and for most options writes one line to the browser's console that names the option:

A value that must be one of a list (theme, size, appearance, execution, retry, refresh-expired, refresh-timeout) or a whole number (tabindex, retry-interval) and is not, gets a warning such as Wicket: theme "blue" is not valid and was ignored, so auto applies.
An action or cdata with a character outside letters, digits, _ and -, or that is too long, gets an error line such as Wicket: action is not valid and was ignored (letters, digits, _ and -; up to 32 characters).
A language that is not written like a language code, such as es or es-MX, is ignored with no line. A well-formed code that Wicket does not have shows English (Languages).
A true-or-false option is false when its value is false or 0, and true for anything else. It never gets a line.
A callback given by name, such as data-callback="onToken", writes a warning such as Wicket: callback names "onToken", which is not a function on window. when window has no such function.

The script removes spaces from the start and end of every text option (sitekey, action, cdata, language and response-field-name), so data-sitekey=" wk_... " works.

The widget's own Appearance setting (theme, size and language, in the dashboard or the API) applies to theme, size and language wherever the page sets none.

The script's address

Section titled The script's address

The script's address takes two parameters.

render: explicit turns off drawing a widget in every wicket-widget element. The page then calls wicket.render() itself. Any other value, or none, draws them as soon as the page is ready.
onload: The name of a function on window that the script calls once it is ready, such as onWicketLoad. A name may have dots, such as app.onWicketLoad.

Options

Section titled Options

Option	Values	Default
`sitekey`	The widget's site key, which starts with `wk_`. A secret key, which starts with `wks_`, is refused (The site key).	Required
`action`	Up to 32 letters, digits, `_` and `-`. Your server reads it from the verify answer.	None
`cdata`	Up to 255 letters, digits, `_` and `-`. Your server reads it from the verify answer.	None
`theme`	`auto` follows the visitor's colour scheme. `light`. `dark`.	`auto`
`language`	`auto` takes the first language the visitor's browser lists that Wicket has. Or a code from Languages, such as `es` or `es-MX`.	`auto`
`size`	`normal` is 300 by 65 px. `flexible` fills its container, at least 300 px wide and 65 px high. `compact` is 150 by 140 px.	`normal`
`appearance`	`always` shows the widget from the start. `execute` shows it once the check starts. `interaction-only` shows it only when the visitor has to act.	`always`
`execution`	`render` starts the check when the widget is drawn. `execute` waits for `wicket.execute()`.	`render`
`retry`	`auto` starts the check again after a network or server error. `never` does not.	`auto`
`retry-interval`	Milliseconds between automatic retries: a whole number above 0 and below 900000.	`8000`
`refresh-expired`	`auto` starts a new check when the token expires. `manual` shows a Check again button instead. `never` shows none.	`auto`
`refresh-timeout`	The same, for a box the visitor did not tick in time.	`auto`
`tabindex`	The tab index of the widget's frame: a whole number, 0 or more.	`0`
`response-field`	`true` adds a hidden field with the token to the container. `false` does not.	`true`
`response-field-name`	The name of that field.	`wicket-response`
`feedback-enabled`	`true` lets a visitor whose check failed report it. `false` takes the link away.	`true`
`offlabel-show-privacy`	`true` keeps the Privacy link on a widget that does not show Wicket's name. `false` takes it away.	`true`
`offlabel-show-help`	The same, for the Help link.	`true`

Notes on the options:

appearance and execution work together: Widget modes shows what each pair does.
A widget that shows Wicket's name always shows its Privacy and Help links. offlabel-show-privacy and offlabel-show-help only matter on a widget whose owner turned the name off.
The frame can be taller than its size when a message needs more lines in the visitor's language. Give the container the min-height for its size, and let it grow (Reserve the widget's height).

The site key

Section titled The site key

A secret key (wks_...) in sitekey is never drawn. The script writes the error line Wicket: render: this is a secret key, which never goes on a page. Use the site key that starts with wk_., calls your error-callback with unknown_sitekey, and shows no widget. Rotate the secret key if it was ever on a public page (Rotate the secret key). With no sitekey at all, the line reads Wicket: render: the widget has no site key. Add data-sitekey to the container or pass sitekey., and the callback receives the same code.

Callbacks

Section titled Callbacks

A callback is a function in the options object, or the name of a function on window in a data- attribute, such as data-callback="onToken". An error in your callback does not stop the widget.

Option	Called	With
`callback`	The visitor passed and the token is in the field.	The token, a string.
`error-callback`	The check could not finish.	An error code. Return `true` to say you handled it: the script then writes no line to the console.
`expired-callback`	The token expired.	Nothing.
`timeout-callback`	The box was not ticked in time.	Nothing.
`before-interactive-callback`	The widget is about to ask the visitor to tick a box.	Nothing.
`after-interactive-callback`	The visitor ticked the box.	Nothing.
`unsupported-callback`	The visitor's browser cannot run the check.	Nothing. Return `true` to say you handled it: the script then writes no line to the console.

Functions of window.wicket

Section titled Functions of window.wicket

ref is the id that wicket.render returned, the container element, or a selector. With no ref, a function acts on the first widget on the page.

Function	What it does
`wicket.render(container, options)`	Draws a widget in an element or a selector and returns its id. It returns nothing, and writes a line to the console, when the container is not on the page. A container that already has a widget returns that widget's id.
`wicket.execute(ref, options)`	Starts the check of a widget whose `execution` is `execute`. `options` may carry `action` and `cdata` for this check.
`wicket.reset(ref)`	Throws the token away. The check starts again at once when `execution` is `render`, and waits for `wicket.execute()` when it is `execute`.
`wicket.remove(ref)`	Takes the widget, its frame and its hidden field off the page.
`wicket.getResponse(ref)`	The current token, or `undefined` when there is none.
`wicket.isExpired(ref)`	`true` when the token has expired.
`wicket.ready(callback)`	Calls `callback` once the script is ready, at once when it already is.

Error codes

Section titled Error codes

The error-callback receives one of these. A check the visitor did not tick in time is not an error: it goes to timeout-callback.

Code	The widget shows	What happened	The script retries
`network`	Could not reach Wicket. Check your connection	The visitor's browser could not reach Wicket.	Yes
`rate_limited`	The same	The visitor's network started too many checks in a minute.	Yes
`internal`	The same	Wicket could not finish the check.	Yes
`failed`	We could not check this browser	The check refused the visitor.	No
`unknown_sitekey`	This site's check is not set up for this page, with the code	No widget has this site key, or the page gave none.	No
`widget_disabled`	The same	Our team turned the widget off.	No
`hostname_not_allowed`	The same	The page's hostname is not on the widget's list.	No
`unsupported`	This browser cannot run the check	The browser has no Web Workers or WebCrypto, or the page is not served over HTTPS.	No

With retry set to auto, the script starts the check again after the retry-interval, up to five times in a row. A configuration error also writes one line to the console that names the site key and what to change. Troubleshoot Wicket says what to do for each code.

Languages

Section titled Languages

ar (drawn right to left), bg, cs, de, en, es, fr, hi, id, it, nl, pl, pt, ro, ru, tr, uk and vi. A code with a region, such as es-MX, uses its first part. A code Wicket does not have uses en. The widget loads only the language it shows. The frame's title is in the same language, taken from the lang of your page when language is auto.

Section titled Related