# 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.

Source: https://www.coritan.com/docs/wicket/widget-options/

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](/docs/wicket/add-wicket-to-your-site/) shows them in use.

## 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

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](#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

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

| 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](#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](#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](/docs/wicket/widget-modes/#appearance-and-execution) 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](/docs/wicket/add-wicket-to-your-site/#reserve-the-widgets-height)).

## The site key {#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](/docs/wicket/widget-settings/#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

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](#error-codes). 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 {#functions}

`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

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](/docs/wicket/troubleshooting/) says what to do for each code.

## 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`.

## Related

- [Add Wicket to your site](/docs/wicket/add-wicket-to-your-site/)
- [Widget modes](/docs/wicket/widget-modes/)
- [Troubleshoot Wicket](/docs/wicket/troubleshooting/)
- [Verify a token on your server](/docs/wicket/verify-tokens/)