Your web app users on mobile browsers see the same Appcues Web SDK experiences as desktop users — but smaller screens can shift elements, change selectors, and clip content. This guide covers how to build and optimize web experiences for mobile web visitors.

This article is about web experiences viewed on mobile browsers. If you are building native mobile app experiences with the Appcues Mobile SDKs (iOS, Android, React Native), see Mobile Overview instead.

What works on mobile web

Not every experience type renders the same on small screens. Here is what to expect:

If your Flow only uses Modals and Slideouts, it will likely look fine on mobile web without any changes. Element-based content is where you will need to put in extra work.

Build with a dual-tab setup

The Appcues Builder needs a full desktop-sized viewport to work properly — it does not function well in a narrow mobile view. To build content that work on mobile web, use two browser tabs side by side:

• Tab 1 (Builder): Your application at full desktop size with the Appcues Chrome Extension active. This is where you build and edit your experience.
• Tab 2 (Mobile preview): The same page in Chrome DevTools device mode, simulating a mobile device. This is where you inspect elements and find the correct CSS selectors for the mobile layout.

Set up the mobile preview tab

1. Open a second browser tab and navigate to the same page in your application.
2. Open Chrome DevTools (Cmd + Option + I on Mac, Ctrl + Shift + I on Windows).
3. Click the device toggle icon in DevTools (or press Cmd + Shift + M / Ctrl + Shift + M) to enter responsive mode.
4. Select a device preset (e.g., iPhone 14) from the dropdown, or choose Responsive and manually set the viewport width.

You now have a desktop view for building and a mobile view for inspecting how elements appear on smaller screens.

Why this matters

Responsive web apps can render completely different elements depending on screen size. A navigation menu visible at desktop width may become a hamburger menu on mobile — with different HTML elements and CSS selectors. If you place a Tooltip on the desktop version of a nav item, that same selector may not exist in the mobile layout.

Optimize element-based experiences for mobile

Tooltips, Pins and Embeds attach to specific DOM elements via CSS selectors. When the layout changes at smaller viewports, those elements can move, resize, or be replaced entirely. Here is how to handle it.

Find the mobile selector

1. In Tab 2 (mobile preview), right-click the element you want to target and select Inspect.
2. Note the element's CSS selector — its ID, class names, or data- attributes.
3. Compare this to the selector for the same element in the desktop view. If they match, no extra work is needed. If they differ, continue below.

Apply the mobile selector in the Builder

1. In Tab 1 (Builder), select the step to adjust.
2. Open the Placement tab in the sidebar.
3. Switch to the Manual tab.
4. Enter the mobile-specific CSS selector. To support both desktop and mobile, use a comma-separated list — Appcues will match the first available element: .desktop-nav-link, .mobile-menu-link
5. The first selector that matches an element on the page is used. 

When using a comma-separated selector list (e.g., .desktop-nav-link, .mobile-menu-link), only one of those selectors can be present on the page at a time. If both selectors match visible elements simultaneously, the content will error and not show. Comma-separated selectors work best when the desktop and mobile elements are mutually exclusive (e.g., one is hidden by a media query while the other is visible).

If your selectors overlap or the experience differs significantly between devices, see Target Mobile Web Users separately.

Use Auto placement (Tooltips and Pins only)

Set the Tooltip/Pin alignment to Auto in the Placement tab. Auto placement dynamically positions the step on whichever side of the target element keeps it within the viewport. This prevents clipping on small screens where a fixed "bottom" or "right" position might push the step off-screen.

Position near center (Tooltips and Pins only)

Place the step as close to the center of the screen as possible. Elements near the edges of a mobile viewport leave less room for the Tooltip to render without getting cut off.

Target mobile web users separately

If the desktop and mobile versions of your app are significantly different — different layouts, different navigation, different features — consider creating two separate Flows instead of optimizing one for both.

Use the _deviceType auto-property

Appcues automatically detects whether a web user is on a desktop or mobile device and sets the _deviceType auto-property. Use this in your audience targeting:

1. Open your Experience's Settings > Audience.
2. Add a condition: User Property > _deviceType > is > mobile (for the mobile Flow) or desktop (for the desktop Flow).
3. This lets you build each version specifically for its screen size without worrying about cross-device selector conflicts.

When to use two versions

• Your app's mobile layout is substantially different from desktop (e.g., tabbed navigation vs. sidebar)
• You want different content or messaging for mobile users
• The same Tooltip tour does not translate between screen sizes because too many selectors differ

When a single version is enough

• Your Flow only uses Modals and Slideouts (fully responsive)
• The elements you are targeting have the same selectors across screen sizes
• You only need to adjust one or two step placements

Video walkthrough

Additional tips

• Create a mobile-specific theme. Build a separate theme with larger tap targets, bigger fonts, and more padding. Apply it to your mobile-targeted Flows for a better reading experience on small screens.
• Test across viewport sizes. Use the Responsive option in DevTools (instead of a fixed device) and drag the viewport width to check different breakpoints. Elements can shift at specific widths based on your app's CSS media queries.
• Ask your dev team about breakpoints. If you are unsure when your app switches from desktop to mobile layout, your development team can tell you the CSS media query breakpoints (e.g., below 768px).
• Preview/Test before publishing. After building, resize your browser to a mobile width and preview the Flow to confirm every step renders correctly.

Confirm it worked

• Preview each step of your exerience at a mobile viewport size in the Builder.
• Verify that element-based steps appear on the correct elements and are not clipped.
• If using separate versions, confirm that the _deviceType targeting is set so each version only appears on the intended device.