Selectors tell Candu where to insert your content on a page. In most cases, we recommend placing Candu content using the Chrome Extension or a Snapshot, which automatically generates a selector for you.
However, these methods sometimes rely on “best guesses,” and the generated selector may not always be the most stable or reliable. In those cases, defining your own selector can give you more control.
When to create a selector manually
You may want to define your own selector if:
Dynamic CSS classes or IDs – When classes or IDs change from page view to page view, or from user to user.
Shifting page structure – When sections of the page move around or aren’t consistently called out in the DOM.
Whenever possible, we recommend adding custom IDs or data attributes to your HTML to create stable selectors. But if you don’t have that flexibility, manual selectors are the next best option.
Features of selectors
Candu selectors use standard CSS selector syntax with a few restrictions:
We don’t support the
:nth-childoperator, since it can become unstable when Candu elements are inserted into the DOM.All other common selectors, combinations, and nesting rules work as expected.
Basic CSS selectors
Here are the most common selectors you’ll use:
Class selector (
.)
Targets elements by their class name..button-primary
Matches any element with
class="button-primary".ID selector (
#)
Targets a single element by its unique ID.#welcome_page
Matches the element
<div id="welcome_page">…</div>.
More advanced selectors
You can also combine selectors to be more specific:
Multiple selectors on the same element
#foo.example
Targets an element with both
id="foo"andclass="example".Descendant selectors
#foo .bar
Targets any element with
class="bar"that is nested inside the element withid="foo".Type selectors
#foo p
Targets
<p>elements inside the element withid="foo".:nth-of-type()#list li:nth-of-type(2)
Targets the second
<li>inside#list.
(Note:nth-childis not supported, butnth-of-typeis.)
Candu-specific selector
Candu also supports a custom extension:
:contains("text")div:contains("Example")Targets a
<div>containing the text “Example.”Can only be used at the end of a selector.
Useful when no stable ID or class is available, but the element always contains unique text.
Case sensitive —
:contains("Example")will not matchexampleorEXAMPLE.
💡 Tip: Watch out for localization — if the text changes for different languages, the selector may no longer match.
How to apply a manual selector in Candu
You can define selectors directly inside the Candu Editor in two ways:
Option 1: Placement Toolbox (fastest)
Open the Candu Editor.
Click the Placements icon on the right-hand toolbar.
In the Where will your content go? section, click Edit next to the HTML Selector.
Enter your selector (e.g.
#welcome_page).If you’re working on a snapshot, you’ll see updates in real time.
Option 2: Content Settings
In the Candu Editor top bar, click Content Settings.
Go to the Placements tab.
Either:
Click the ✏️ icon next to an existing placement to update its selector.
Or, click Add a new placement to define a new one.
Enter your selector and save.
⚠️ Note: Selector changes take effect immediately. You do not need to republish your content after editing a selector.
Limitations
Selectors do not work inside iframes or the shadow DOM.
You cannot target Candu-inserted content itself. Selectors only apply to the underlying host page.