Articles on: Upsell Popup App

How to use the CSS/XPATH Selector configuration

CSS/XPath Selector Trigger


Use the CSS/XPath Selector trigger when you want an offer popup to open after a customer clicks a specific element on your storefront.


This trigger is useful when the standard Add to cart or Checkout triggers do not match your theme layout or custom functionality.




Example uses:


  • A custom checkout button
  • A payment button in a cart drawer
  • A "Buy now" button or sticky add-to-cart area
  • A custom banner, image, or call-to-action block
  • A theme element added by another app


What To Enter


Enter one CSS selector or one XPath expression that matches the clickable element you want to use as the trigger.


Examples:


  • button.checkout-button
  • a[href="/checkout"]
  • [data-testid="sticky-atc"]
  • //button[@name="checkout"]
  • //*[@data-testid="sticky-atc"]


The selector must match the element on your live storefront that the customer clicks.


If the clickable element contains nested content, such as an icon or text inside a button, that is fine. The app checks the clicked element and its parent elements, so the trigger can still work when the customer clicks inside the target element.


Important Behaviour


  • This trigger activates on click.
  • The selector field accepts CSS or XPath.
  • For CSS selectors, you can enter multiple selectors separated by commas if you want the same offer to open from any of those elements.
  • For XPath, enter one full XPath expression only.
  • For this trigger type, the offer is triggered by the selector itself. Product targeting is not required.


CSS Or XPath: Which Should I Use?


Use CSS in most cases. It is usually shorter, easier to test, and easier to maintain.


Use XPath when:


  • The element does not have a stable class, ID, or attribute
  • You need to target an element based on its position in the HTML structure
  • You cannot build a reliable CSS selector for the theme element


If both are possible, use CSS first.


How To Find A CSS Selector


  1. Open your storefront in Chrome, Edge, or another Chromium browser.
  2. Go to the page where the element appears.
  3. Right-click the element you want to use.
  4. Click Inspect.
  5. In the developer tools panel, the matching HTML element will be highlighted.
  6. Look for a stable identifier on that element, such as:
  • a data-* attribute
  • a name attribute
  • an href
  • a clear class name added by the theme or app
  1. Build a selector using one of the recommended formats below.
  2. Paste that selector into the CSS/XPath Selector field in the app.
  3. Save the offer and test it on your storefront.



Use the simplest selector that uniquely identifies the correct element.


Good options:


  • button.primary-checkout
  • button[name="checkout"]
  • a[href="/checkout"]
  • [data-testid="cart-checkout-button"]
  • [aria-label="Checkout"]


You can combine a tag and a class:


  • button.checkout-button
  • div.footer__payment


You can also target by attribute:


  • [data-button="checkout"]
  • [data-testid="buy-now-button"]


How To Find An XPath


  1. Open your storefront in Chrome, Edge, or another Chromium browser.
  2. Go to the page where the element appears.
  3. Right-click the element and click Inspect.
  4. In developer tools, confirm the correct HTML element is highlighted.
  5. Look for stable attributes on that element, such as data-*, name, href, aria-label, or a permanent class.
  6. Build an XPath that targets that exact element.
  7. Paste the XPath into the CSS/XPath Selector field in the app.
  8. Save the offer and test it on your storefront.


Recommended XPath examples:


  • //button[@name="checkout"]
  • //a[@href="/checkout"]
  • //*[@data-testid="sticky-atc"]
  • //div[@data-button="checkout"]



  • Start your XPath with // or /.
  • If you use a grouped XPath, wrap it like (//button[@name="checkout"])[1].
  • Prefer stable attributes over long structural paths.
  • Keep it as short as possible while still matching the correct element.


Avoid relative XPath expressions that start with . such as .//button[@name="checkout"], because they may not be recognised correctly in this trigger field.


Choose Stable Selectors


Prefer values that are unlikely to change.


Best choices:


  • data-* attributes
  • name
  • href
  • aria-label
  • clear, permanent class names added by the theme or app


Acceptable choices:


  • simple tag and class combinations such as button.cart-checkout
  • simple container selectors such as div.cart-footer
  • short XPath expressions based on stable attributes


Avoid These Selectors


Do not use selectors that are likely to break after a theme update or app change.


Avoid:


  • very long selectors copied directly from the browser
  • selectors with many parent elements
  • generated classes such as xYz12ab or svelte-abc123
  • position-based CSS selectors such as :nth-child(3)
  • long, fragile XPath paths copied from browser tools
  • IDs or classes that look random or change between pages


Avoid examples like:


  • body > div:nth-child(2) > div > button
  • .svelte-bm3bl2
  • //*[@id="shopify-section-template--12345"]/div[2]/div/button


Simple Rules


  • Use the clickable element itself when possible.
  • Keep the selector short.
  • Use one selector per offer unless you want the same offer to open from multiple elements.
  • If several similar elements exist, make the selector more specific so only the correct one matches.
  • If the selector matches too many elements, the popup may open from the wrong click.
  • If the selector matches nothing, the popup will not open.


Testing Checklist


After saving your offer:


  1. Open the storefront page where the element appears.
  2. Click the target element.
  3. Confirm the correct popup opens.
  4. Test desktop and mobile if your theme uses different layouts or different buttons.
  5. If it does not work, inspect the element again and choose a more stable selector or XPath.


AI Assistance


If you are not comfortable writing selectors, you can ask an AI tool to help.


Example prompt:


I need a stable CSS selector or XPath for this storefront element. Please avoid long or fragile selectors and prefer data-*, name, href, or other stable attributes. Here is the HTML: [paste element HTML here]


If possible, ask the AI to give you:


  • one recommended CSS selector
  • one fallback XPath
  • a short explanation of why those selectors should be stable


Need Help?


If you are unsure which selector to use, contact our support team and include:


  • the storefront URL
  • the page where the trigger appears
  • a screenshot of the element
  • the HTML for that element from your browser inspector, if available


That will help us suggest the most reliable CSS selector or XPath for your theme.


Updated on: 15/04/2026

Was this article helpful?

Share your feedback

Cancel

Thank you!