> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usertick.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Triggers

> When a website survey opens: smart triggers for frustration, finished reading, engagement, hesitation and searching, page load, delay, scroll, exit intent, clicks, forms, copied text, videos, custom events and more, and how often it returns.

A trigger opens a website survey for a visitor who matches its [targeting](https://docs.usertick.com/surveys/targeting.md). Triggers are set in the **Triggers** tab of the survey's **Targeting** step, under **Conditions**. **Add condition** adds a condition, each condition type can be added once, and **Combination** sets how the conditions combine:

* **Any**: the survey opens as soon as the first condition fires.
* **All**: every condition must fire before the survey opens.

Three more controls apply to the conditions:

* **Then wait**: after the conditions are met, the survey waits up to 60 seconds before opening. For example, "scroll past half the page, then wait five seconds" lets the visitor finish reading first.
* **Don't interrupt**: after the conditions are met (and after **Then wait**), the survey waits until the visitor stops typing, scrolling, selecting text or watching a video with sound, for up to 10 seconds. A visitor filling in a form keeps typing undisturbed, and the survey opens at the first pause.
* **Devices**: each condition can apply to some of the survey's devices only. Exit intent on desktop and a 20-second delay on phones is one survey with two conditions. The editor warns when a device has no condition that opens the survey.

An [embedded survey](https://docs.usertick.com/surveys/design.md#display) has no trigger conditions: it shows as soon as its element is on the page.

## Smart triggers

Smart triggers read several signals on the page and open the survey on a score or a pattern, at the moment a question is most useful. Usertick counts these signals in the visitor's browser with fixed rules; nothing is recorded or sent.

| Condition | Opens when | Options |
| - | - | - |
| **Frustration** | Signals add up over the last 30 seconds: a rage click counts 3 points, a click on a link or button that changes nothing counts 2, a page error 2 and a form that fails validation 1 | **Level**: Low opens at 3 points (one rage click), Medium at 5, High at 7. Default Medium |
| **Finished reading** | The visitor reaches the end of the content after spending enough time to read it. Usertick estimates the reading time at 230 words a minute; the survey opens once 85% of the content has been on screen and the page has been visible for half that time | Selector of the content. Empty reads the page's article, else its main section |
| **Engaged visitor** | An engagement score reaches the level: time on the site up to 40 points (full at 2 minutes), scroll depth on the page up to 20 (full at 75%), pages viewed up to 20 (full at 4) and clicks, copies and form entries up to 20 (full at 5) | **Level**: Low opens at 40, Medium at 60, High at 80. Default Medium |
| **Hesitation** | The visitor comes back to a page viewed earlier in the visit, or returns to the tab after 30 seconds or more away. A reload doesn't count | None |
| **Can't find it** | The visitor opens a fourth page after less than 10 seconds on each of the three before it, searches the site a second time with different words, or goes straight back from a page to the one before it for the second time | None |

A smart trigger combines with the others like any condition. With a page rule such as `/pricing`, **Hesitation** opens the survey when a visitor comes back to the pricing page. **Can't find it** reads site searches from the address (the `q`, `s`, `query`, `search`, `keyword` or `term` parameter); a search that doesn't change the address isn't seen.

## The conditions

| Condition | Fires when | Options |
| - | - | - |
| **On page load** | The page finishes loading | None |
| **After a delay** | The page has been visible for N seconds; time in a background tab doesn't count | Seconds, 0 allowed, default 3 |
| **Time on site** | The visitor has spent N seconds with the tab in focus, across all pages of one visit | Seconds, default 60 |
| **On scroll** | The visitor scrolls past N percent of the page height | Percent, default 50 |
| **Exit intent** | On desktop, the cursor moves toward the browser bar; on phones and tablets, a fast scroll back to the top | None |
| **On element click** | The visitor clicks an element that matches a CSS selector | Selector |
| **On element hover** | The visitor hovers over a matching element for a moment (needs a mouse, so it never fires on phones and tablets) | Selector, dwell time |
| **Element seen** | At least half of a matching element is on screen, including elements added to the page later | Selector |
| **On form submit** | A form on the page is submitted | Selector, default `form` (every form) |
| **Form abandoned** | The visitor types into a form and then leaves it for a while without submitting | Selector, default `form` |
| **Text copied** | The visitor copies text from the page, or from the elements a selector names, such as `pre, code` for code samples. Copying from the survey itself doesn't count | Selector, empty for the whole page |
| **Video watched** | The visitor has played a video on the page to a set share of its length. Only the time actually played counts, so skipping ahead doesn't. Videos embedded from YouTube or Vimeo play in a frame the page can't read, so they don't count | Selector, empty for every video; watched share, 10 to 100%, default 90 |
| **On idle** | No click, key press, scroll or tap for N seconds; the timer pauses while the tab is hidden | Seconds, default 30 |
| **Rage click** | Four or more fast clicks in the same spot | None |
| **Pages viewed** | The visitor has viewed N pages in this browser session, including in-app route changes | Count, default 3 |
| **Page error** | The first uncaught error or unhandled promise rejection on the page; errors from the widget itself are ignored | None |
| **Custom event** | Your code calls `Usertick.trigger("name")`, optionally with matching properties, on the first call or a later one | Event name, property rules, calls needed |

### Triggers by plan

**On page load**, **After a delay**, **Time on site**, **On scroll**, **Exit intent**, **On idle** and **Pages viewed** work on every plan. **On element click**, **On element hover**, **Element seen**, **On form submit**, **Form abandoned**, **Text copied**, **Video watched**, **Rage click**, **Page error** and **Custom event** are advanced triggers, available on the Starter plan and above. The smart triggers, **Don't interrupt** and **Double the wait after each close** are available on the Pro plan and above.

On a plan without a trigger, the condition shows "Your plan doesn't include this trigger. To publish, remove it or upgrade to Starter." (or Pro), and the survey can't be published until the condition is removed or the plan is upgraded. **Don't interrupt** and **Double the wait after each close** show the same kind of note. After a downgrade, a published survey keeps its triggers until it is published again.

## Custom events

The custom event condition connects a survey to moments only your app knows about:

```js theme={null}
// after a successful checkout
Usertick.trigger("checkout_completed", { plan: "pro", total: 249 });
```

When the survey's custom event is named `checkout_completed`, the survey opens at that call. The name matches in any case, and spaces around it don't count. Events sent before the snippet finishes loading are queued and replayed.

Property rules narrow the condition further. Under **Only when the event includes**, **Add property rule** adds a rule over the properties your code sends, such as `plan` is `pro` or `total` is at least `100`. The survey then opens only for calls whose properties pass every rule, so one event can open different surveys for different customers. The operators are the same as for trait rules (is, is not, contains, starts with, greater than, is set and so on), and property names match in any case. A condition without rules opens on any call with that name. See the [SDK reference](https://docs.usertick.com/developers/sdk/reference.md#trigger).

**Calls needed** opens the survey on a later matching call instead of the first. With 5, a survey after `report_exported` asks once the visitor has exported five reports. Usertick counts the matching calls in the visitor's browser, across visits, on the pages where the survey can show, and starts the count again after the survey opens.

## Frequency and politeness

Triggers decide when a survey opens. **Repeat behavior** under **Show frequency**, in the **Display rules** tab, decides whether the same visitor sees it again:

* **Until answered** (the default): the survey shows on each visit until the visitor responds. If the visitor closes it, the survey waits until the next visit.
* **Once**: the survey shows once per visitor, whether or not they respond.
* **Every N days**: the survey shows again after each **Cooldown duration**, up to **Maximum displays**, and **After submission** sets what happens once the visitor responds: **Don't show again**, **Show again after the cooldown** or **Keep showing**.
* **Every visit**: the survey shows on every page load that meets the other rules, which mainly suits launchers and testing.
* **Wait after closing**: for every behavior except Once, the survey waits a set number of days after a visitor closes it without answering.
* **Double the wait after each close**: with **Wait after closing**, the first close waits the days set and the second twice as long. After the third close, the survey doesn't show to that visitor again.

When several surveys are ready on the same page, all of them wait for their trigger and the first one to fire opens. Only one popup shows at a time: the others wait until it closes and can then open under their own trigger and repeat behavior. A side button or an embedded survey never holds a popup back.

These rules are kept in the visitor's browser. A browser that blocks cookies and site data can't remember what it showed, so by default a survey that depends on that memory (every behavior except Every visit) is hidden there instead of showing on every page load. Turning off **Hide when the browser blocks storage** shows it there anyway.

> [!TIP]
>
> Examples that work well: hesitation on the pricing page to ask what held the visitor back; frustration anywhere for a bug report survey with a [screenshot question](https://docs.usertick.com/surveys/question-types.md#screenshot); finished reading on the docs for "Was this page helpful?"; can't find it with a question about what the visitor was looking for; a custom event after checkout with `total` at least 100 for a high-value order survey.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.