> For the complete documentation index, see [llms.txt](https://docs.userlane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.userlane.com/assistance/in-app-guidance/creating-contextual-actions.md).

# Creating Contextual Actions

Contextual Actions deliver Userlane content automatically when a defined condition is met in the application, instead of waiting for a user to ask for help.

A Contextual Action is a rule that delivers Userlane content when something specific happens in the application. It is not content itself. Guides, tooltips, validators, tags, and tasks are built as usual, and a Contextual Action decides when they show up.

Content that sits in [the Assistant](/assistance/the-assistant.md) only reaches people who go looking for it. A Contextual Action brings it to them instead: a tooltip that appears only on screens where the control it explains is visible, a guide that starts when a form opens, a tag that counts clicks inside one workflow and nowhere else.

Every rule has two halves:

* **Contexts.** The conditions being watched. A Context reads as a statement: if Element is Present.
* **Actions.** The content delivered when those conditions are true.

## How a Contextual Action works

### Conditions a Context can check

A Context is a type, an operator, and a value.

<table><thead><tr><th width="105.1875">Type</th><th width="266.1397705078125">What it watches</th><th width="163.658447265625">Operator</th><th>Value</th></tr></thead><tbody><tr><td><strong>Element</strong></td><td>One interface element in the application, found by a selector</td><td><strong>Is</strong>, <strong>Is Not</strong></td><td><strong>Present</strong>, <strong>Clicked</strong>, <strong>Selected</strong>, <strong>Focused</strong></td></tr><tr><td><strong>User</strong></td><td>Whether the person is interacting with the application</td><td><strong>Is Active</strong>, <strong>Is Not Active</strong></td><td>A duration in minutes or seconds, for <strong>Is Not Active</strong></td></tr><tr><td><strong>Content</strong></td><td>How the person has interacted with a named piece of Userlane content</td><td><strong>Is</strong></td><td><strong>Completed</strong>, <strong>Viewed</strong>, <strong>Closed</strong>, <strong>Clicked</strong></td></tr></tbody></table>

An element condition responds to what is on the screen. That holds up better than matching the page address, because many applications keep one address while the screen underneath changes completely.

A content condition chains content together: a message after a guide someone finished, or a follow-up after a guide someone closed partway through.

### Contexts are reusable

A Context belongs to the application, not to one rule. Editing it updates every rule that uses it from the next page load, so fixing a selector[^1] once fixes all of them.

### Combining conditions

**Match All** needs every Context to be true at the same time, and is on by default. **Match Any** fires as soon as one is true. The setting covers the whole rule, and conditions do not nest inside each other.

### What a Contextual Action can trigger

<table><thead><tr><th width="235.8359375">Group</th><th width="184.93359375">Content type</th><th>Behavior available</th></tr></thead><tbody><tr><td>Delivery content</td><td>Guide</td><td><strong>Start</strong>, optionally from a chosen step</td></tr><tr><td>Delivery content</td><td>Tooltip</td><td><strong>Load</strong>, <strong>Hide</strong></td></tr><tr><td>Delivery content</td><td>Validator</td><td><strong>Load</strong>, <strong>Show</strong>, <strong>Hide</strong></td></tr><tr><td>Measurement</td><td>Tag</td><td><strong>Load</strong></td></tr><tr><td>Measurement</td><td>Task</td><td><strong>Load</strong></td></tr></tbody></table>

**Load** gets content ready without showing it. A loaded tooltip waits for the element it belongs to, a loaded tag starts counting, and a loaded task comes under the rule.

Pointing a rule at a tag or a task measures one workflow rather than every click on that element everywhere it appears.

### What happens after it fires

Delivery content does not always stay. What happens next depends on the content type and on the kind of condition behind it.

<table><thead><tr><th width="129.85546875">Content type</th><th width="327.43359375">State condition: Present, Selected, Focused</th><th>Event or activity condition: Clicked, Is Active, Is Not Active</th></tr></thead><tbody><tr><td>Tooltip</td><td>Hides when the condition stops being true, and comes back if it is met again</td><td>Stays for the session</td></tr><tr><td>Validator</td><td>Hides when the condition stops being true, and stops checking entries</td><td>Stays for the session</td></tr><tr><td>Tag</td><td>Stops counting, and starts again when the condition returns</td><td>Counting carries on</td></tr><tr><td>Guide</td><td>Runs to the end or until the user exits. The condition only decides when it starts</td><td>Runs to the end or until the user exits</td></tr><tr><td>Task</td><td>Measurement carries on once loaded. The condition only decides when it loads</td><td>Measurement carries on once loaded</td></tr></tbody></table>

### How often it fires

Each Action carries its own frequency. **Once** is the default. **Always** fires again every time the conditions are met. A single rule can hold a guide that starts once and a tooltip that comes back every time.

### Existing targeting still applies

[Audience](/administration/audiences.md) and display rules on the content decide who is eligible. A Contextual Action only decides the moment.

Unpublished content can be added to a rule, and nothing happens until it is published. You can build the rule first and switch it on later.

## Creating a Contextual Action

Contextual Actions are built in the Editor[^2], in the **Contextual Actions** section.

{% stepper %}
{% step %}

#### Open Contextual Actions

Select **Contextual Actions** in the Editor navigation. The list holds every rule for the application. **Context List**, at the top of the list, opens the conditions saved for that application.
{% endstep %}

{% step %}

#### Create and name the rule

Select **Create**. Two empty columns open, **Contexts** and **Actions**, and **Match All** is already on. The name field starts as "Contextual Action" and can be typed over at any point. The rule does nothing until it is activated.
{% endstep %}

{% step %}

#### Add one or more Contexts

Select **Add Context**. You can reuse a saved Context, or build a new one from one of the three types.

To build a new one, choose **Element**, **User**, or **Content**, then set the operator and the value. An element is picked directly on the page, and its selector can be adjusted by hand afterward. A **User** condition asks for a duration when the condition is inactivity. A **Content** condition takes the specific piece of content first, then the value.

Saving adds the Context to the application's list as well as to this rule.
{% endstep %}

{% step %}

#### Add one or more Actions

Select **Add Action**. The dialog searches content by name and filters by published status, so a draft can be found and wired up before it goes live. Expand a content type, pick the item, and add it.

A guide cannot share a rule with other visible content. Tags and tasks show nothing on screen, so they can sit alongside anything.
{% endstep %}

{% step %}

#### Preview

**Preview** stays unavailable until the rule has at least one Context. It checks the rule's conditions live and reports which ones are met, without delivering anything to users.
{% endstep %}

{% step %}

#### Save or activate

**Save** keeps the rule without switching it on. **Activate** switches it on, and it starts checking conditions for end users.
{% endstep %}
{% endstepper %}

## What Contextual Actions do not do

* **No history.** Content conditions look at the session in progress. A condition such as "has ever completed this guide" is not available.
* **One guide at a time.** A rule that starts a guide cannot also deliver other visible content. Measurement content is the exception.
* **Tags cannot depend on user activity.** A tag counts clicks, and a click contradicts an inactivity condition.
* **No override of targeting.** A rule cannot show content to someone whom audience or display rules exclude.
* **No nesting.** **Match All** and **Match Any** apply across the whole rule.

## Relevant articles

{% content-ref url="/pages/1S0Ysrf45iMPMs4rp5yk" %}
[Creating guides](/assistance/in-app-guidance/creating-guides.md)
{% endcontent-ref %}

{% content-ref url="/pages/KhbHHZ0ThLa5Pkd5bNXI" %}
[Creating tooltips](/assistance/in-app-guidance/creating-tooltips.md)
{% endcontent-ref %}

{% content-ref url="/pages/DbuU3EtVubYDfoPt5F6W" %}
[Create a tag in the Editor](/intelligence/tags/create-a-tag-in-the-editor.md)
{% endcontent-ref %}

{% content-ref url="/pages/BkK6BtMQAoCXdpgXSBa5" %}
[Targeting](/assistance/content-operations/targeting.md)
{% endcontent-ref %}

{% content-ref url="/pages/CTLIhTmnhzt4Gwl4dF9h" %}
[Manage selectors](/assistance/in-app-guidance/creating-selectors/manage-selectors.md)
{% endcontent-ref %}

## FAQ

<details>

<summary>What is a Contextual Action?</summary>

A Contextual Action is a rule that delivers Userlane content automatically when a defined condition is met in the application. It combines one or more Contexts, which are the conditions, with one or more Actions, which are the content to deliver.

</details>

<details>

<summary>Does a Contextual Action replace audience and display rules?</summary>

No. Audience and display rules on the content decide who is eligible. A Contextual Action decides when that content appears for the people who already qualify.

</details>

<details>

<summary>Can unpublished content be added to a Contextual Action?</summary>

Yes. A draft can be added as an Action and the rule built around it. Nothing reaches users until the content is published.

</details>

<details>

<summary>Can a guide and a tag sit in the same Contextual Action?</summary>

Yes. Tags and tasks show nothing on screen, so they fire alongside a guide. Other visible content cannot share a rule with a guide.

</details>

<details>

<summary>What happens when a condition stops being true?</summary>

Tooltips, validators, and tags respond to the change. A tooltip or validator triggered by a state condition hides, and a tag stops counting. Guides and tasks carry on.

</details>

[^1]: A selector is the rule Userlane uses to find an element on the page. If the application changes, the selector may need refining so it still matches.

[^2]: The Editor is the workspace where Userlane content is built, separate from the portal where content is targeted and analytics are viewed.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.userlane.com/assistance/in-app-guidance/creating-contextual-actions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.