> 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/best-practices/tooltips-choose-write-and-place-them-well.md). # Tooltips: choose, write, and place them well When to use hints and beacons, how to avoid common placement mistakes, and how to combine tooltips with other content types. A tooltip adds context to a specific element on the page without interrupting the workflow. When used well, tooltips answer the question a user has before they think to search for it. When used poorly, they clutter the interface with information nobody needs. The difference is placement, type, and restraint. ## How it works {% stepper %} {% step %} #### Choose the right type Userlane has two [tooltip](/assistance/in-app-guidance/creating-tooltips.md) types. The choice depends on whether the goal is to explain or to attract attention.
TypeHow it appearsBest for
HintAn info icon is always visible next to the target element. The detail text appears when the user hovers over it.Explaining a field, icon, or button that users encounter during their normal workflow
BeaconA pulsating circle is always visible next to the target element. The detail text appears when the user clicks it.Drawing attention to a new feature, an underused function, or a call to action
Hints are passive: they sit on the page and wait for the user to notice them. Beacons are active: the pulsating animation draws the eye. Use hints for ongoing reference (field explanations, icon labels) and beacons for temporary attention (new feature launches, process changes). Once a user clicks a beacon and reads the content, the beacon does not reappear for that user in that browser. Hints reappear on every visit. {% endstep %} {% step %} #### Write short, specific content A tooltip that requires scrolling is too long. Keep the description to one or two sentences. If the explanation needs more space, link to a guide instead. **Good tooltip content:** * What a field expects ("Enter the cost center code assigned to this department, for example 4200-FIN.") * What a button does ("Submitting this form sends the request to the approver. It cannot be edited after submission.") * Why an element matters ("This checkbox determines whether the record is included in the monthly compliance report.") **Bad tooltip content:** * A paragraph explaining a feature's history * Instructions that belong in a guide * Generic reminders ("Remember to save your work") Provide tooltip text in every application language. A tooltip that appears in the wrong language confuses more than it helps. {% endstep %} {% step %} #### Place tooltips where they help, not where they block Tooltip placement determines whether end users find them useful or annoying. **Do not cover important content.** A hint icon placed on top of a required field label hides the label when the tooltip opens. Place the icon next to the element, not on it. **Do not block the workflow.** If a tooltip opens over a button the user needs to click next, it interrupts the process. Test the placement by walking through the workflow with the tooltip active. **Do not place hints on hover-menu triggers.** This is the most common tooltip placement mistake. When a hint is placed on an element that opens a dropdown or flyout on hover, the user cannot read the tooltip and use the menu at the same time. Moving the cursor from the element to the tooltip box closes the hover menu. For elements with hover menus, use a beacon instead. Beacons activate on click and stay open until dismissed, so they do not interfere with hover behavior. To annotate an element inside a hover menu, place a beacon on the trigger element. Link it to a guide that walks through the menu interaction. {% endstep %} {% step %} #### Combine tooltips with other content types Tooltips are most effective when they connect to the broader content set rather than standing alone. **Link a tooltip to a guide.** A hint on a form field can include a button that launches a related guide. The user reads the short explanation and, if they need more detail, starts the guide without leaving the page. A beacon on a new feature can link to the guide that teaches the full workflow. **Use tooltips alongside announcements.** When launching a new feature, use an announcement to inform end users about the change and a beacon on the feature itself to remind them where it is. The announcement reaches everyone. The beacon persists on the page for users who missed the announcement. **Trigger tooltips with Contextual Actions.** A [Contextual Action](/assistance/in-app-guidance/creating-contextual-actions.md) can show a tooltip automatically when a defined condition is met, for example when a user lands on a page for the first time or when a specific element appears on the page. This turns a passive tooltip into a proactive nudge without requiring the user to notice the icon or animation first. **Target tooltips with audiences and display rules.** A tooltip explaining a feature only available to administrators should target the administrator audience[^1]. A tooltip relevant only on the settings page should have a display rule[^2] scoped to that URL. {% endstep %} {% endstepper %} ## How to know it is working Check two things in the portal analytics: 1. **View rate.** What proportion of users who visit the page see (hover over or click) the tooltip? A low view rate on a hint may mean the icon is not noticeable or the placement is poor. A low view rate on a beacon may mean the feature it highlights is rarely visited. 2. **Link click rate.** If the tooltip links to a guide, how often do users follow that link? A high click rate means the tooltip is doing its job as a bridge to deeper content. A low click rate on a tooltip with a linked guide may mean the short description already answers the question, which is also fine. {% hint style="warning" %} **Caveat.** A tooltip with zero views is not necessarily broken. If the target element is behind a tab, inside a collapsed section, or on a page that few users visit, the tooltip may be correctly placed but poorly targeted. Check whether the display rule and audience match the users who actually reach that element. {% endhint %} ## Relevant articles {% content-ref url="/pages/KhbHHZ0ThLa5Pkd5bNXI" %} [Creating tooltips](/assistance/in-app-guidance/creating-tooltips.md) {% endcontent-ref %} {% content-ref url="/pages/L1pTwQHW0TmAMoPDFhLR" %} [Creating Contextual Actions](/assistance/in-app-guidance/creating-contextual-actions.md) {% endcontent-ref %} {% content-ref url="/pages/HGvA2yvKz1f1Ux8Nm4PS" %} [Guides: build, maintain, and make them effective](/best-practices/guides-build-maintain-and-make-them-effective.md) {% endcontent-ref %} {% content-ref url="/pages/msLcBEUrbA35YGwlU0Rx" %} [Announcements: write, target, and schedule them](/best-practices/announcements-write-target-and-schedule-them.md) {% endcontent-ref %} ## FAQ
When should a tooltip be a guide instead? If the explanation requires more than two sentences, or if the user needs to complete steps to understand the concept, use a guide. Tooltips explain one element. Guides teach a process. A tooltip can link to a guide for users who need the longer version.
Can a tooltip be scheduled to appear and disappear automatically? Tooltips do not support scheduling. They are either published (visible) or unpublished (hidden). To make a tooltip appear at a specific time, publish it manually. To make it disappear, unpublish it or delete it. For time-sensitive messaging, use announcements, which support scheduling.
What happens if the target element does not exist on the page? The tooltip does not appear. No error is shown to the end user. If the target element is removed during an application update, the tooltip silently stops appearing. Check tooltip analytics periodically: a tooltip with views dropping to zero may indicate the target element no longer exists.
Can tooltip colors be customized per tooltip? No. Hint icon color and beacon circle color are set at the application level in the portal under **Customize**. All hints share one color and all beacons share another. Individual tooltip color customization is not available.
[^1]: An audience is a reusable group of users defined by rules about their attributes, behavior, or tag interactions. Audiences control who sees which content and can also filter analytics. [^2]: A display rule is a URL-based condition that controls which pages content appears on. --- # 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/best-practices/tooltips-choose-write-and-place-them-well.md?ask=&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.