> 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-tooltips.md).

# Creating tooltips

Tooltips add an explanation to one element on a page. They come in two types: hints, which open on hover, and beacons, which open on click.

A tooltip is a small overlay attached to one element on a page. It stays on the page and shows its content when someone hovers over or clicks it, depending on its type. Each tooltip holds a short description and, optionally, a button that starts a guide.

<div data-with-frame="true"><figure><img src="https://259567114-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF6bxg8i3T6U4vZ3k7PHi%2Fuploads%2Fgfyg0Xsl8Tzq8AYqzOnM%2FEditor_Tooltips-02-e1671025760679-1024x576.webp?alt=media&#x26;token=2e03fb9e-8786-4875-8a2e-3b92ada79112" alt="A tooltip open beside an element in an application"><figcaption><p>A tooltip attached to an element on the page.</p></figcaption></figure></div>

## The two types: hints and beacons

A tooltip is either a hint or a beacon. The type decides how the content opens.

A **hint** opens on hover. It can show a small icon next to the element, or it can open when someone hovers over the element itself with no icon at all. A hint reappears on every visit, so it works as permanent reference.

A **beacon** opens on click and is marked by an animated circle. Once someone opens a beacon and closes it, that beacon does not appear again for that person in that browser. Beacons suit temporary attention, such as a new feature or a changed process.

<table><thead><tr><th width="123.64453125">Type</th><th width="158.8125">How it opens</th><th width="134.28125">How it closes</th><th>What it suits</th></tr></thead><tbody><tr><td>Hint with icon</td><td>Hover over the icon next to the element</td><td>Move the pointer away</td><td>Explaining a field, icon, or button encountered during normal work</td></tr><tr><td>Hint without icon</td><td>Hover over the element itself</td><td>Move the pointer away</td><td>Inline help embedded in the page, where an extra icon would add clutter</td></tr><tr><td>Beacon</td><td>Click the animated circle</td><td>Click elsewhere or press <strong>Escape</strong></td><td>Drawing attention to something new or easy to miss</td></tr></tbody></table>

## When to use a tooltip

Use a tooltip when the answer fits in one or two sentences and belongs next to a single field, icon, or button. When the explanation needs steps, [build a guide](/assistance/in-app-guidance/creating-guides.md) and link it from the tooltip instead. When the message is about a change rather than an element, use an [announcement](/assistance/change-communication/announcements.md).

Tooltip performance is reported in the portal alongside every other content type: views, view rate, and linked guide clicks.

## Create and publish a tooltip

The tooltip panel opens beside the application and stays there throughout. Its settings sit on four tabs: **Type**, **Config**, **Segmentation**, and **Publish**. **Language** sits above the tabs and switches which language version you are editing. **Preview** and **Save** are available at the bottom of the panel at any point.

{% stepper %}
{% step %}

#### Select the target element

Open the Editor[^1] on the application, select **Tooltips**, then **Create**. Pick the element the tooltip attaches to. The application stays interactive during selection, so open a dropdown or dialog first if the element sits inside one.

The chosen element becomes the target element[^2], and Userlane stores a selector[^3] to find it again. The tooltip appears only when that element is present on the page.
{% endstep %}

{% step %}

#### Choose hint or beacon

The **Type** tab opens next. Choose the tooltip type (**Hint** or **Beacon**), set an icon, and configure the hint position. **Set icon** controls whether an icon appears next to the element or the tooltip opens from the element itself. **Set hint position** controls placement: **Auto** finds space automatically, and **Manual** offers fixed positions.

{% hint style="warning" %}
**Elements that open a menu on hover.** A hint on an element that opens a dropdown or flyout on hover cannot be read and used at the same time. Moving the pointer toward the content box closes the menu. Use a beacon on that element instead, because a beacon opens on click and stays open until it is closed.
{% endhint %}
{% endstep %}

{% step %}

#### Write the content

Type the description directly into the tooltip box shown over the selected element. The box previews the end result as you type.

Keep the description to one or two sentences. A tooltip that needs scrolling is too long, and the box has a fixed width that cannot be changed.

Write the description in every language the application serves. Switch versions with **Language** at the top of the Editor. See [Languages](/assistance/content-operations/languages.md) for setting up languages and translating content in bulk.
{% endstep %}

{% step %}

#### (Optional) Link a guide

On the **Config** tab, you can link a guide to the tooltip. The tooltip then shows a link that starts that guide. Leave the guide set to **None** when the description is the whole answer.
{% endstep %}

{% step %}

#### Target the tooltip

On the **Segmentation** tab, set **Choose your audience** and **Choose where the tooltip is shown**.

Both default to the widest setting, **Everyone** and **Everywhere**. Left alone, the tooltip appears for everyone wherever its target element is found, which is rarely the intention.

{% hint style="info" %}
**Where audiences are built.** [Audiences](/administration/audiences.md) are created and edited in the portal, not here. The tab links straight to them. The portal area and this tab are still labeled segments.
{% endhint %}
{% endstep %}

{% step %}

#### Preview and check placement

Select **Preview** and walk through the workflow with the tooltip open. Confirm that the content box does not cover the element it explains, and that it does not sit over the control someone needs to use next. Placement problems are visible here and expensive to find after publishing.
{% endstep %}

{% step %}

#### Publish

Open the **Publish** tab and publish the tooltip. It becomes visible to everyone the audience and location settings match.

**Save** stores the tooltip without publishing it, leaving it visible only inside the Editor. Unpublishing later returns it to that state.
{% endstep %}
{% endstepper %}

{% hint style="success" %}
**Result.** The tooltip is live on the target element for everyone the audience and location settings match. It appears in tooltip analytics from the first time it is published.
{% endhint %}

## Troubleshooting

<table><thead><tr><th width="166.23828125">Symptom</th><th width="217.36328125">Possible cause</th><th>What to do</th></tr></thead><tbody><tr><td>End users do not see the tooltip</td><td>It was saved but never published</td><td>Publish it. Unpublished tooltips appear only in the Editor.</td></tr><tr><td>The tooltip stopped appearing after an application update</td><td>The target element changed and no longer matches</td><td>Open <strong>Config</strong> and select <strong>Reselect element</strong>, or adjust the match with <strong>Refine Selector</strong>.</td></tr><tr><td>The Editor reports that the element cannot be found</td><td>The element is absent from the current page, or behind a closed menu</td><td>Navigate to the page or open the menu, then reselect the element.</td></tr><tr><td>The tooltip opens in the wrong place</td><td>Page transforms, nested frames, or browser zoom away from 100 percent</td><td>Set the position manually on the <strong>Type</strong> tab, or attach the icon to the element itself using <strong>Refine Selector</strong>.</td></tr><tr><td>The icon lags behind the element while scrolling</td><td>Positions refresh on an interval rather than continuously</td><td>Attach the icon to the element itself using <strong>Refine Selector</strong>.</td></tr><tr><td>A beacon does not come back for someone who closed it</td><td>Working as designed. Dismissal is stored in that browser</td><td>Nothing to fix. Clearing browser storage resets it. Dismissal does not carry across browsers or devices.</td></tr><tr><td>The same tooltip appears on pages it should not</td><td>The selector matches a repeated element, such as a common button</td><td>Narrow the location setting on <strong>Segmentation</strong>, then narrow the match with <strong>Refine Selector</strong> if it still appears.</td></tr></tbody></table>

## Relevant articles

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

{% content-ref url="/pages/ekWOHrKxU3Yp6xV24fPM" %}
[Userlane content types](/assistance/content-operations/authoring/userlane-content-types.md)
{% endcontent-ref %}

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

{% content-ref url="/pages/JKbJ88H839VzRksHakFJ" %}
[Announcements](/assistance/change-communication/announcements.md)
{% endcontent-ref %}

## FAQ

<details>

<summary>What is a beacon?</summary>

A beacon is a tooltip that opens on click and is marked by an animated circle next to its target element. It is one of the two tooltip types, alongside the hint. Once someone opens a beacon and closes it, that beacon does not appear again for that person in that browser.

</details>

<details>

<summary>Can a tooltip be copied?</summary>

Yes. A tooltip can be duplicated from the tooltips overview. The copy is independent of the original, so duplicating is a way to draft a change to a live tooltip without editing the live one.

</details>

<details>

<summary>Can tooltip text be translated in bulk?</summary>

Yes. Tooltip descriptions are included in the bulk export and import used for translating content. Only the description is exported. The tooltip name is internal and stays out of the file.

</details>

<details>

<summary>Why does a tooltip appear in the Editor but not for end users?</summary>

It was saved but never published. Saving keeps a tooltip inside the Editor only. Publishing makes it visible to everyone the audience and location settings match.

</details>

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

[^2]: The target element is the field, button, or other element on the page that a tooltip attaches to.

[^3]: 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.


---

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