Skip to main content

​
Why it Matters

To display content relative to your existing application’s elements or to capture feature usage events, you need to define an element selector so that GuideWhale can reference these elements later. This allows you to precisely target any element on the page and display content in the right context.

​
Search Fallback

When content relies on a target element to be shown, it’s essential to define a fallback action to take when the target element is not found. This ensures that your content is displayed correctly, even if the target element is not found on the target page. The fallback action can either dismiss the content or fallback to another position that doesn’t require the target element.

​
Target Element Selection

​
CSS Selector

GuideWhale supports flexible target element selection for displaying content:
  • Automatic: The Chrome extension generates a CSS selector for the selected element automatically.
  • Manual: Users can enter a custom CSS selector to precisely target any element on the page.
This ensures your content appears exactly where you want it, regardless of your app’s structure.

​
Automatic

The Chrome extension automatically generates an optimal CSS selector when you visually select an element from your application.

​
Manual

When you need precise control over element selection, you can manually define a CSS selector. This is useful when the automatic selector doesn’t capture the right element or when you want to target elements dynamically.

​
Using Browser Console to Inspect Elements

Before writing a CSS selector, you need to inspect the HTML structure of your target element:
  1. Open Developer Tools
    • Right-click on the element you want to target
    • Select “Inspect” or “Inspect Element”
    • Alternatively, press F12 or Cmd+Option+I (Mac) / Ctrl+Shift+I (Windows/Linux)
  2. Locate the Element
    • The Elements/Inspector tab will open with the element highlighted
    • Examine the element’s HTML structure, classes, IDs, and attributes
    • Note the parent and sibling elements for context
  3. Test Your Selector
    • Open the Console tab in Developer Tools
    • Use document.querySelector('your-selector') to test if your selector finds one element
    • Use document.querySelectorAll('your-selector') to see all matching elements
    • If the element is highlighted in the browser, your selector is correct
Example: 
// Test if your selector finds the element
document.querySelector('#submit-button')

// Check how many elements match
document.querySelectorAll('.action-button').length

​
CSS Selector Types

GuideWhale supports all standard CSS selectors. Here are the most common types:
1. ID Selector
Targets an element with a specific ID. IDs should be unique on a page. Syntax: #elementId Example: 
#submit-button
#user-profile-menu
#checkout-form
HTML: 
<button id="submit-button">Submit</button>
2. Class Selector
Targets elements with a specific class. Multiple elements can share the same class. Syntax: .className Example: 
.primary-button
.nav-item
.card-header
HTML: 
<button class="primary-button">Click Me</button>
3. Element Selector
Targets all elements of a specific type. Syntax: elementName Example: 
button
div
input
h1
HTML: 
<button>Any Button</button>
4. Attribute Selector
Targets elements with specific attributes or attribute values. Syntax: [attribute] or [attribute="value"] Examples: 
[data-testid="login-button"]
[type="submit"]
[aria-label="Close"]
[href^="https://"]  /* starts with */
[href$=".pdf"]      /* ends with */
[class*="button"]   /* contains */
HTML: 
<button data-testid="login-button">Login</button>
<input type="submit" value="Submit">
5. Descendant Selector
Targets elements that are descendants of another element. Syntax: ancestor descendant Example: 
.sidebar .menu-item
#header nav a
.modal .close-button
HTML: 
<div class="sidebar">
  <ul>
    <li class="menu-item">Item</li>
  </ul>
</div>
6. Direct Child Selector
Targets elements that are direct children of another element. Syntax: parent > child Example: 
.nav > li
#menu > .item
.container > div
HTML: 
<ul class="nav">
  <li>Direct child</li>
</ul>
7. Multiple Classes
Targets elements with multiple specific classes. Syntax: .class1.class2 Example: 
.btn.btn-primary
.card.featured
.nav-item.active
HTML: 
<button class="btn btn-primary">Primary Button</button>
8. Pseudo-classes
Targets elements in a specific state. Syntax: selector:pseudo-class Examples: 
button:hover
input:focus
li:first-child
div:nth-child(2)
a:not(.disabled)
9. Combining Selectors
You can combine multiple selectors for more specific targeting. Examples: 
/* Element with class */
button.primary-action

/* Multiple conditions */
div#container.active[data-role="main"]

/* Complex combination */
.sidebar nav > ul li.active a

​
Best Practices

  1. Use Stable Selectors
    • Prefer data-* attributes or IDs over auto-generated classes
    • Avoid selectors based on dynamic classes (e.g., css-123abc)
  2. Keep It Simple
    • Use the shortest selector that uniquely identifies the element
    • Avoid overly complex selectors that may break easily
  3. Test Thoroughly
    • Always test your selector in the browser console
    • Verify it works across different states (logged in/out, different pages)
  4. Consider Dynamic Content
    • For lists or repeated elements, use :nth-child() or attribute selectors
    • Account for elements that may load asynchronously
Example Testing Flow: 
// 1. Test if selector finds element
const element = document.querySelector('.submit-btn');
console.log(element); // Should show the element

// 2. Verify it's unique
const allMatches = document.querySelectorAll('.submit-btn');
console.log(allMatches.length); // Should be 1 for unique targeting

// 3. Highlight to confirm
element.style.border = '3px solid red';