> 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-selectors.md). # Creating selectors What a selector is, why one stops matching, and what to do about it. A selector identifies a single element on a web page. Every piece of Userlane content, whether it is a guide step, a tooltip, a tag, or a Contextual Action, stores a selector that tells the browser extension[^1] which element to attach to. Each time the content runs, Userlane matches that selector against the live page and highlights or acts on the result. This article explains what selectors contain, why they stop matching, and what you can do when one breaks. If you manage your own content, you can [refine selectors and write selector rules](/assistance/in-app-guidance/creating-selectors/manage-selectors.md) directly in the Editor[^2]. {% content-ref url="/pages/CTLIhTmnhzt4Gwl4dF9h" %} [Manage selectors](/assistance/in-app-guidance/creating-selectors/manage-selectors.md) {% endcontent-ref %} ## What a selector contains When content is created in the Editor, Userlane captures the details that identify the target element: a CSS selector, the element's position among matching elements on the page, and how it is nested if it sits inside an iframe or a Shadow DOM tree. An application-level setting can make the Editor capture the element's visible text as an extra matching criterion on every new recording. It is off by default. While it is off, visible text is captured only if you add it through the **Refine Selector** flow. Those details matter across the product. [Guides](/assistance/in-app-guidance/creating-guides.md), [tooltips](/assistance/in-app-guidance/creating-tooltips.md), [validators](/assistance/in-app-guidance/validators.md), and [Contextual Actions](/assistance/in-app-guidance/creating-contextual-actions.md) all depend on selectors to find their target. So do [tags](/intelligence/tags/create-a-tag-in-the-editor.md) and [tasks](/intelligence/tasks/create-a-task-in-the-editor.md), which use them to recognize the action being measured. A broken selector affects both the help a user sees and the analytics behind it. {% hint style="info" %} **Where selectors reach.** Selectors find elements in the main document, inside iframes, and inside Shadow DOM trees (a browser feature that lets part of a page keep its own separate structure). {% endhint %}
The Editor showing the selector details captured for a target element

The selector details the Editor captures for a target element.

## Why selectors break A selector describes an element as it looked when the content was created. Anything that changes that description can break the match.
CauseWhat happens
The application changedA redesign, an upgrade, or a new wrapper around part of the page. The element can look identical on screen and still no longer match its selector.
Position shiftThe selector expects a numbered match and fewer or more matching elements now exist on the page.
Language changeThe selector matches on visible text and the interface language changed, so the text no longer matches.
## When a selector breaks Selectors can only be fixed in the Editor. You can fix it there yourself, or [contact Userlane support](/support/contact-and-escalation.md). Partners who built the content usually have their own contact route for this. If you contact support, these details speed up the fix: 1. The name of the guide, tooltip, or tag. 2. The page URL where the problem occurs. 3. What happens instead: nothing appears, or the content highlights the wrong element. 4. Whether it happens every time or only on certain pages. 5. Any recent change to the application, including upgrades and configuration changes. Only the selector needs adjusting. The content itself, its text, settings, and history, stays intact. ## Preventing breakage before an application release Application releases are the most common cause of broken selectors, and they are the easiest to handle in advance. Before a release goes live, check the affected screens in a staging environment and adjust selectors in the Editor where needed. Your users then never reach an updated screen with broken content. ## Relevant articles {% content-ref url="/pages/CTLIhTmnhzt4Gwl4dF9h" %} [Manage selectors](/assistance/in-app-guidance/creating-selectors/manage-selectors.md) {% endcontent-ref %} {% content-ref url="/pages/1S0Ysrf45iMPMs4rp5yk" %} [Creating guides](/assistance/in-app-guidance/creating-guides.md) {% endcontent-ref %} {% content-ref url="/pages/brm1JWKM3yHqhKU1n5G2" %} [A tour of the Editor](/assistance/a-tour-of-the-editor.md) {% endcontent-ref %} {% content-ref url="/pages/x0VOtqZaqLMPxH6L3eGw" %} [Contact and escalation](/support/contact-and-escalation.md) {% endcontent-ref %} ## FAQ
Why does a guide step highlight the wrong element? The most common cause is a position shift. The selector expects a numbered match, and the number of matching elements on the page has changed since the content was created. The same guide can work on one screen and miss on another if the element count differs.
Can a broken selector be fixed without rebuilding the content? Yes. Only the selector is adjusted in the Editor. The guide, tooltip, or tag keeps its content, settings, and history.
Will an application upgrade break all of our content? Rarely. Selectors break only where the upgrade changed the structure of a screen, so the effect is normally limited to the screens that were redesigned. Checking the affected screens before the release reaches users catches most breaks early.
Does changing the interface language break selectors? Only selectors that match on visible text. Selectors based on element attributes are not affected.
[^1]: The browser extension is the component that runs Userlane inside the applications your organization uses. It is the default deployment method. [^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-selectors.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.