Selectors

Every visual edit is anchored to a selector — a string that tells the snippet runtime which element to modify. Picking a stable selector is the difference between a test that runs for months and one that breaks the next time engineering touches the page.

The selector priority chain

When you click an element in the Visual Editor, it inspects the element and its ancestors and generates a candidate selector using the following priority order. The first strategy that produces a unique match wins.

data-avsb-target — A custom attribute reserved for A vs B testing. Add this to elements you plan to test, and the editor will always prefer it.
data-test-id — A common convention used by QA and end-to-end testing tools. Stable enough to use as a selector for experiments.
data-* attributes — Any other data-* attribute, in document order.
id — The HTML id attribute, when one is present and unique on the page.
Class combination — A short list of class names that, taken together, uniquely identify the element.
Structural path — A CSS path that walks up the DOM tree using tag names and :nth-child(). Used as a last resort because it breaks easily.
Text content — Matches a button or link by the visible text it contains. Useful for stable copy that rarely changes.

In the editor panel, the Selector field shows the generated string. A small badge next to it ranks the confidence: STRONG, MEDIUM, STRUCTURAL, or TEXT_ONLY. You can also click Edit selector to override the suggestion and write your own.

The confidence pill in the Inspector

When you pick an element, the right Inspector's header card shows a coloured pill next to the element tag. The pill reflects the strongest candidate the editor produced for that element:

Green pill — “Strong” — The strongest selector is anchored to a data-avsb-target, data-test-id, another stable data-* attribute, or a unique id. Safe to ship.
Amber pill — “Medium” — The strongest selector is a class combination. Usually fine, but a styling-system refactor or a class rename will break it.
Red pill — “Structural” or “Text-only” — The strongest selector relies on DOM position (nth-of-type) or visible text. Sibling reorders or copy edits will break the selector. Consider asking engineering to add a data-avsb-target before saving.

Hover the pill to see the per-candidate audit: each selector the editor captured for the element, plus a short reason explaining what could break it (“Selector relies on nth-child position — sibling reordering will break it”, “Selector matches by text content — copy edits in the customer page will break it”, etc.). The audit notes update live as you move between elements.

A red pill is not a blocker — the editor will still save the change. But it's a signal worth checking against the live customer page. If the experiment is a one-off promo, structural is usually fine. If the variation is intended to live for months, escalate to engineering for a data-avsb-target.

Confidence levels

Every generated selector is tagged with one of four confidence levels. The badge appears next to the selector in the editor and is also reported in the variation's history.

STRONG — Backed by data-avsb-target, data-test-id, another stable data-* attribute, or a unique id. Safe to assume the selector survives unrelated UI changes.
MEDIUM — Class combination. Usually stable, but a rename or refactor of the styling system can break it.
STRUCTURAL — Walks the DOM by tag and child index. Fragile to any reordering of siblings. The editor warns you when this is the best it can do.
TEXT_ONLY — Matches by visible text content. Will stop matching the moment the copy changes — including translation or a typo fix.

The data-avsb-target attribute

For any element you plan to test more than once, the most reliable approach is to add a dedicated data-avsb-target attribute. The editor checks for it first, and your developers can guarantee that page redesigns preserve it.

Recommended pattern

1<h1 data-avsb-target="hero-headline">
2  Save 30% on your first order
3</h1>
4
5<button data-avsb-target="primary-cta">
6  Get started
7</button>

Use kebab-case identifiers that describe the role of the element, not its appearance — hero-headline, not large-red-text. The role outlives the design.

How selectors resolve at runtime

When a visitor is bucketed into your variation, the snippet runtime walks each change in the variation and resolves its selector against the live DOM. If the selector finds exactly one element, the edit applies. If it finds zero or more than one, the runtime logs a warning and skips that change. Changes are applied before any user-authored variation JavaScript or CSS, so you can rely on them being in place when your custom code runs.

Selecting multiple elements

Some edits target every match, not just the first — for example, hiding a banner that appears in both the header and the footer. When you switch the edit to Apply to all matches, the runtime applies the change to every element returned by the selector. The editor warns you when a selector accidentally matches more than one element so you can decide which behaviour is intentional.

Styling frameworks like CSS-in-JS often emit class names such as css-1abc234 that change every build. The editor will flag these as MEDIUM confidence at best — and they typically break within days. Either ask engineering to add a data-avsb-target attribute or override the selector manually before saving.