Skip to main content

Unstable Selector Detection Warnings

We have added unstable selector detection to the UI submodule service functions. When a CSS selector passed to a UI function relies on DOM structure that is not guaranteed to remain stable, a [HAPI] UNSTABLE SELECTOR WARNING is logged to the browser console in non-production environments.


HAPI Elements does not guarantee DOM stability inside widget iframes. The HTML structure, element types, and DOM order may change between releases. However, IDs and class names are kept backwards compatible. Selectors that depend on element types, child or sibling combinators, or positional pseudo-classes may stop working when the internal markup changes.


The following unstable constructs are detected:

  • Element type selectors (div, span, p, etc.)
  • Child combinator (>)
  • Adjacent sibling combinator (+)
  • General sibling combinator (~)
  • Positional pseudo-classes (:nth-child, :first-child, :last-child, :nth-of-type, :only-child, etc.)
  • Pseudo-elements (::before, ::after, etc.)

We recommend using only class selectors (.class), ID selectors (#id), and attribute selectors ([data-attr]) when targeting elements inside widget iframes. If you need to target a specific element that does not currently have a stable ID or class, contact your VONQ Partner Account Manager to request that one be added.


The warning is logged once per unique selector to avoid console noise. The function call is still executed normally -- no calls are blocked or modified. This feature complements the existing UI Service Functions Spam Call Detection and Improper Widget Placement Detection Warnings to help developers catch integration issues early during development.