Appcues is built so that non‑technical teams can create and manage in‑product experiences without relying on engineering. However, in modern frontend frameworks like React or Ember, auto‑generated CSS selectors and highly dynamic markup can make it hard for those teams to reliably target elements in the Appcues builder. If your app relies heavily on these patterns, a bit of intentional setup on the development side goes a long way. In this guide, we’ll walk through practical options for adding stable classes, IDs, or data attributes so your teammates can build flows and pins in Appcues easily and without friction.

1. Prefer stable class names / IDs over dynamic attributes

Avoid targeting elements by:

• Auto‑generated IDs (like #el-12345, #react-select-9-option-1)
• Framework-specific classes that change on every build
• Data that changes frequently (like timestamps, user IDs, random tokens)

Instead:

• Add clear, semantic class names for key UI elements:
  • btn-primary
  • btn-save-changes
  • nav-sidebar-item
  • card-feature-announcement
• Or stable IDs when the element is truly unique on the page:
  • id="save-settings-button"
  • id="profile-avatar"
  • id="billing-upgrade-cta"

These should be static in code, not generated at runtime.

2. Introduce a “product education” or “appcues” naming convention

Create a simple, consistent convention just for Appcues targets. For example:

• data-appcues="primary-cta"
• data-appcues="sidebar-settings-link"
• data-appcues="onboarding-step-1-card"

Or with classes:

• class="appcues-target appcues-primary-cta"
• class="appcues-target appcues-upgrade-banner"

Guidelines:

• Use data-* attributes when you do not want to affect styling.
• Use a shared vocabulary (e.g. primary-cta, secondary-cta, nav-settings, modal-confirm, etc.), documented in a short internal doc.

3. Make targets generic but descriptive

Non‑technical users should be able to guess what to select just by reading it in the Appcues builder.

Examples:

• Bad: .css-1a2b3c4 or #btn-97621
• Good: .appcues-primary-cta or [data-appcues="profile-save-button"]

For repeated elements, devs can still make them targetable in groups:

• .appcues-sidebar-item
• .appcues-feature-card

Then you can refine with nth‑of‑type or specific page context if needed, but the base selector is human‑readable.

4. Add attributes to the actual clickable / visible element

Make sure the attribute or class is applied to:

• The button or link users click
• The card, tile, or row you want to highlight
• The input or field label that the content should attach to

Avoid putting the Appcues‑specific selector only on a high‑level div that contains many clickable areas, unless the whole container is the target.

5. Avoid re‑rendering or replacing target elements unnecessarily

If your frontend frequently:

• Destroys and re‑creates DOM nodes
• Changes keys/IDs on every render
• Wraps elements in changing containers

…it becomes harder to keep Appcues flows stable.

Do:

• Keep keys and structure stable for core UX elements Appcues will target.
• Avoid unnecessary DOM reshuffles around primary CTAs, nav items, or forms that you plan to guide users through.
• Ensure that SPA route changes do not constantly recreate the same button with a new dynamic selector.

6. Document the “Appcues targeting” contract

• Create a short internal doc or page listing:
  • The standard attributes (for example, data-appcues) and their naming rules.
  • A catalog of important targets: primary CTAs, onboarding components, key nav links, etc.
• Keep it updated when new features are launched, so non-technical teams can immediately build content on top.

This makes it clear what is “safe” and stable to use in Flows and Pins.

7. Consider environment differences (staging vs production)

If you run Appcues in multiple environments:

• Ensure the same selectors and attributes exist in staging and production.
• Avoid environment‑specific dynamic suffixes in classes/IDs.
• If feature flags change the UI, the underlying target attributes should still be consistent where the element exists.