Appcues targets HTML elements by CSS selector — Flows, Pins, Launchpads, Embeds, and Click-to-Track events all reference selectors in your application. If you rename a class, remove an element, or restructure your DOM, any Appcues content that depends on that selector breaks silently. No alert — it just stops appearing.

Before you ship a frontend change, ask Captain AI or the MCP server to audit your selectors. Both tools check experiences and Click-to-Track events in a single query.

Use Captain AI in Studio

Open Captain AI from the left sidebar in Appcues Studio.

Ask a question that describes the selector or element you're changing. For example:

• "What Appcues content uses the .upgrade-btn selector?"
• "Is anything targeting #onboarding-checklist?"
• "Show me all experiences and events using elements with the class nav-header."

Captain AI returns a list of every experience and Click-to-Track event that references matching selectors, along with their status (published, draft, disabled).

Review the results. If anything depends on the selector you're changing, update your experiences or events before deploying your code change.

Use the MCP server

If you have the Appcues MCP server connected to an AI client like Claude, Cursor, or ChatGPT, you can run the same check without leaving your development environment.

Open your AI client with the Appcues MCP server connected. If you haven't set this up yet, see Use the Appcues MCP Server with your AI tools.

Ask the same kind of question you'd ask Captain AI:

• "Before I remove the .feature-card class, does Appcues use it for anything?"
• "List all Appcues experiences and Click-to-Track events targeting [data-tour='step-3']."

The MCP server queries your Appcues account and returns matching experiences and events directly in your editor or terminal.

This is useful during code review or right before merging a refactor — you can check selectors in context without switching to Studio.

What to do if something depends on a selector

If Captain AI or the MCP server returns results, update the Appcues content before deploying your code change:

Experiences (Flows, Pins, Launchpads, Embeds): Open the experience in the Appcues Builder and update the element targeting to match your new selector.

Click-to-Track events: Open the Click-to-Track editor in the Builder, find the event, and update or re-select the target element. See Track events without code using Click to Track. Note that event names cannot be changed after saving — only the selector can be updated.

Publish the Appcues changes first, then ship your code.

Prevent future breakage with stable selectors

CSS classes change during refactors. DOM structure shifts between redesigns. To avoid repeated breakage, assign dedicated attributes to elements that Appcues targets:

Use data-appcues attributes: Add data-appcues="upgrade-cta" or similar to elements you want Appcues to target. These survive CSS refactors because they aren't tied to styling.

Use stable IDs: If your framework supports it, add unique id attributes to key interactive elements. IDs are the most specific and reliable selector type.

Avoid styling classes as selectors: Classes like .btn-primary or .flex-row change when you update your design system.

See Prepare your Frontend for element targeting for more. When you set up a new experience or Click-to-Track event, use the Refine Selection option in the Builder to manually enter a selector based on a stable attribute instead of relying on the auto-detected one.