# Widget modes

> How Managed, Non-interactive and Invisible widgets differ, what a visitor sees in each, how appearance and execution change when it shows, and which to choose.

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

A widget's *mode* decides how much of the check a visitor sees. You choose it when you add the widget, and you can change it later. The page does not set it, so one page can show widgets of all three modes by using three site keys. A second setting, the *appearance*, decides when the widget's frame is on the page at all, and works with every mode.

## What every mode does

Every mode runs the same check. The visitor's browser does a small calculation, called the *proof of work*, and answers a few questions about itself, such as whether a script is driving it. Wicket scores the answer, and the score decides what happens next:

- A clear pass gives the token at once. Most visitors see nothing more than a moment of **Checking your browser…** and then **Success**.
- A score in the middle costs the visitor a little: a click, or more work. The modes differ in which.
- Only near-certain evidence fails a check. Wicket never refuses a visitor on a guess, and ticking the box with a keyboard or a screen reader never counts against a visitor.

Every token is bound to the widget and to your page's hostname, works once, and expires after 300 seconds.

## The three modes

| Mode | API word | What a visitor sees |
| --- | --- | --- |
| Managed | `managed` | A short check, and a box to tick when Wicket is unsure. |
| Non-interactive | `non_interactive` | A short check and never a box. |
| Invisible | `invisible` | Nothing at all. |

### Managed

A Managed widget starts the check at once and shows **Checking your browser…**. Then one of three things happens:

- The visitor passes, and the widget shows **Success**.
- Wicket is unsure, and the widget asks **Confirm you are a person** with a box. The visitor ticks it once. When the answer is still unclear, the widget does one more round of work at a harder level, and then fails the check.
- Wicket is nearly certain the visitor is a script, and the widget shows **We could not check this browser** with a **Try again** button.

The box is a real checkbox. A visitor can tick it with a pointer, a finger, <kbd>Space</kbd> or a screen reader. A box that waits for 120 seconds shows **Time ran out**, and the widget starts again by itself unless `refresh-timeout` says otherwise.

### Non-interactive

A Non-interactive widget shows the same short check and never a box. When Wicket is unsure, the widget gives the visitor's browser more to calculate instead of asking for a click: up to two more rounds, each harder than the one before. The visitor sees **Checking your browser…** for a little longer, and then **Success**.

A visitor Wicket stays nearly certain about gets **We could not check this browser** with a **Try again** button, as in Managed.

### Invisible

An Invisible widget draws nothing and takes no room on the page once its frame has loaded. It checks as a Non-interactive widget does: no box, and up to two harder rounds when Wicket is unsure.

Because the visitor sees nothing, your page decides what to show. The widget gives your code a token through `callback`, and a failed check through `error-callback`, with the code `failed`. Show your own message there, and let the visitor try again by calling `wicket.reset()`.

An Invisible widget usually starts when your code asks it to: set `data-execution="execute"` and call `wicket.execute()` when the visitor submits. [Add Wicket to your site](/docs/wicket/add-wicket-to-your-site/#invisible-widgets) shows how to mark an Invisible widget so the page does not move when it loads.

## Appearance and execution

`appearance` decides when the frame is on the page, and `execution` decides when the check starts. Both are options of the widget's container or of `wicket.render` ([Widget options](/docs/wicket/widget-options/)), whatever the mode.

| `appearance` | The frame is on the page |
| --- | --- |
| `always` | From the moment the widget is drawn. |
| `execute` | Once the check starts. |
| `interaction-only` | Only when the visitor has to act: a box to tick, a failed check, a time-out, an error, a lost connection or an unsupported browser. Out of sight otherwise. |

| `execution` | The check starts |
| --- | --- |
| `render` | When the widget is drawn. |
| `execute` | When your code calls `wicket.execute()`. |

A frame that is not on the page is out of sight and out of the accessibility tree: it takes no room, and a screen reader does not announce it. An Invisible widget is never on the page, whatever its `appearance`.

| You want | Mode | `appearance` | `execution` |
| --- | --- | --- | --- |
| A check that shows from the start | Any but Invisible | `always` | `render` |
| Nothing on the page unless the visitor must tick a box | Managed | `interaction-only` | `render` |
| A check that starts when the visitor submits the form, with a box if needed | Managed | `interaction-only` | `execute` |
| A check that shows only once it starts | Any but Invisible | `execute` | `execute` |
| A check with no widget on the page | Invisible | `interaction-only` | `render` or `execute` |

## When a token expires

A token works for 300 seconds. When they pass, the script empties the hidden field and calls `expired-callback`. Then `refresh-expired` decides what happens, and `appearance` decides whether the visitor sees it:

| `refresh-expired` | What the widget does | With `appearance` set to `interaction-only` |
| --- | --- | --- |
| `auto` (the default) | Starts a new check at once. The widget shows **This check expired** for a moment, then **Checking your browser…**. | The frame stays out of sight. The new check runs unseen, and your `callback` gets the new token. The visitor sees the widget only if the new check needs a box. |
| `manual` | Shows **This check expired** with a **Check again** button, and waits. | The frame comes onto the page for this message, and leaves again when the visitor selects **Check again**. |
| `never` | Shows **This check expired** with no button, and starts nothing. | Nothing appears. |

From the moment a token expires until the next check passes, `wicket.getResponse()` answers `undefined` and `wicket.isExpired()` answers `true`. With `never`, call `wicket.reset()` to start the next check yourself.

A box that nobody ticks is separate. The frame always comes onto the page for **Time ran out**, and `refresh-timeout` takes the same three words with the same effects.

## Choose a mode

- Choose Managed for most forms: sign-up, contact and comment forms. Most visitors never see a box, and the few who do tick it once.
- Choose Non-interactive where a box would be out of place, such as a checkout or a sign-in that must feel instant, and a visitor can wait a moment longer. It costs the visitor time, never a click.
- Choose Invisible when the check runs behind your own button or inside an app that shows its own messages. Your page handles a failed check, because the visitor sees nothing from Wicket.

All three modes run the same check and score it the same way. The mode decides only what Wicket asks of a visitor it is unsure about.

Your server can tell which visitors ticked a box: the verify answer's `metadata.interactive` is `true` for them ([Verify a token on your server](/docs/wicket/verify-tokens/)).

## Try a mode

The [test keys](/docs/wicket/test-keys/) give a widget of each kind without a real widget: a visible one that passes, a visible one that fails, an invisible one that passes and one that fails, and one that shows the box and then passes.

## Next steps

- [Add a widget](/docs/wicket/add-a-widget/) and choose its mode.
- [Change a widget's settings](/docs/wicket/widget-settings/#mode) to switch the mode of a widget you have.
- [Add Wicket to your site](/docs/wicket/add-wicket-to-your-site/#invisible-widgets) to mark an Invisible widget so the page does not move.
- [Widget options](/docs/wicket/widget-options/) for `appearance`, `execution` and the callbacks.