Selectors tell Candu exactly where to insert your content on a page. A selector is a string that identifies a specific HTML element in your page's DOM.
In most cases, you'll use the Chrome Extension or a Snapshot. They automatically create selectors for you by analyzing your page structure. This is fast and works for the majority of placements.
However, automatic selectors aren't always reliable. If your page structure changes after you create the placement, or if your selector is dynamic, Candu may no longer be able to find that element. When Candu can't reliably find the element, your content won't display.
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-child() is not supported because it becomes unstable when Candu inserts elements into the DOM. Use :nth-of-type() instead.
Candu-Specific Selector
Candu also supports a custom extension:
:contains("text")
Useful when no stable ID or class is available, but element always contains unique text. It matches elements that contain the specified text anywhere inside them. Can be combined with any element type, class, or ID:
div:contains("Welcome")
.sidebar:contains("Menu")
#header:contains("Dashboard")
button:contains("Get Started")
.nav-sidebar:contains("Menu")
.nav-menu li:contains("Home")Note: :contains("Example") is case sensitive and will not match example or EXAMPLE.
💡 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
In the floating bar to the right, click Placements
In the "Where will your content go?" section, click Edit next to HTML Selector
Enter your selector (e.g.
#welcome_page).Note: 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 Settings
Go to Placements
Either:
Click the ✏️ icon next to an existing placement to update its selector
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
Testing Your Selector
After defining a manual selector, verify it works correctly. If the selector doesn't highlight any elements:
Open your browser's developer tools (F12)
Use Console and type:
document.querySelector('your-selector-here')If it returns
null, your selector doesn't match any elements on the page
👉 For more detailed troubleshooting: See our complete guide on Troubleshooting Selector Issues
Note on Combining Manual Selectors with URL Rules
Manual selectors work with URL targeting to create precise placement logic:
Example: Dashboard banner only on main dashboard page
Selector:
#dashboard-headerURL rule: Exactly matches
https://app.example.com/dashboard
Example: Feature announcement across product section
Selector:
div:contains("products")URL rule: Starts with
/products
👉 Learn more about URL Targeting
Limitations
Selectors cannot target elements inside iframes or shadow DOM.
You cannot target Candu content. Selectors only apply to your page's existing HTML.
Need help? Reach out via chat or email us at [email protected].