> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guidewhale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Target Element Selection

> Visually select content position and event trigger target elements from inside your web application.

## 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:**

```javascript theme={null}
// 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:**

```css theme={null}
#submit-button
#user-profile-menu
#checkout-form
```

**HTML:**

```html theme={null}
<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:**

```css theme={null}
.primary-button
.nav-item
.card-header
```

**HTML:**

```html theme={null}
<button class="primary-button">Click Me</button>
```

##### 3. Element Selector

Targets all elements of a specific type.

**Syntax:** `elementName`

**Example:**

```css theme={null}
button
div
input
h1
```

**HTML:**

```html theme={null}
<button>Any Button</button>
```

##### 4. Attribute Selector

Targets elements with specific attributes or attribute values.

**Syntax:** `[attribute]` or `[attribute="value"]`

**Examples:**

```css theme={null}
[data-testid="login-button"]
[type="submit"]
[aria-label="Close"]
[href^="https://"]  /* starts with */
[href$=".pdf"]      /* ends with */
[class*="button"]   /* contains */
```

**HTML:**

```html theme={null}
<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:**

```css theme={null}
.sidebar .menu-item
#header nav a
.modal .close-button
```

**HTML:**

```html theme={null}
<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:**

```css theme={null}
.nav > li
#menu > .item
.container > div
```

**HTML:**

```html theme={null}
<ul class="nav">
  <li>Direct child</li>
</ul>
```

##### 7. Multiple Classes

Targets elements with multiple specific classes.

**Syntax:** `.class1.class2`

**Example:**

```css theme={null}
.btn.btn-primary
.card.featured
.nav-item.active
```

**HTML:**

```html theme={null}
<button class="btn btn-primary">Primary Button</button>
```

##### 8. Pseudo-classes

Targets elements in a specific state.

**Syntax:** `selector:pseudo-class`

**Examples:**

```css theme={null}
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:**

```css theme={null}
/* 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:**

```javascript theme={null}
// 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';
```