Guide form factors and properties

Guides and Surveys include six form factors. Each form factor has a set of properties that control how it behaves for the end user.

Form factors

Each form factor shares a similar set of properties.

Modals are a full-focus experience that takes center stage. Use modals to deliver important messages or guide users through a multi-step flow.

Customize your modal with the following:

Pick a layout: classic, horizontal split, or vertical split.
Add a button, and customize what happens when users click or tap it.
Add an image or video. Amplitude places media elements depending on the selected layout.
Animate the text. Text animation causes text to animate in when the guide appears.

Click the three dot menu to access format settings.

Setting	Description
Content layout	Updates the visual ordering of the guide's content.
Title and content alignment	Changes the alignment of the title and body text.
Actions bar	Updates the placement and layout of the guide's buttons.
Click/Tap outside to close	Enables users to click or tap outside of the modal to dismiss it.
Text animation	Enables the modal's text to animate in with a typewriter effect.

A subtle nudge that appears near a contextually relevant element. Use popovers for quick tips or to direct users' attention without interrupting their flow.

Popovers offer many of the same customization options as modals.

Click the three dot menu to access format settings.

Setting	Description
Content layout	Updates the visual ordering of the guide's content.
Title and content alignment	Changes the alignment of the title and body text.
Actions bar	Updates the placement and layout of the guide's buttons.
Z-index	Specify a custom z-index value for the popover.
Text animation	Enables the popover's text to animate in with a typewriter effect.

Pins are persistent markers that remain on screen until a user interacts with them. Use pins to highlight key features or provide contextual help users can refer to.

Pins can advance without CTA clicks

By default, when a user clicks a pin's target element, the tour advances to the next step. You can disable this behavior with the Disable auto-advance on target click setting (web only). The Advance trigger setting in the Pin format settings lets you specify an additional element that also advances the tour when a user clicks it.

Analytics impact for pins not set to open by default

For pin guides that aren't set to Open by default, clicking the target element marks the guide as complete without generating a Guide Viewed event. This can result in more Guide Completed events than Guide Viewed events when users interact with the target element without first opening the pin beacon.

Pins offer different customization options than modals or popovers. Toggle between opening them by default, or start them closed. Use Show mask to display a semi-transparent overlay that highlights the pinned element and dims the rest of the screen.

Pins can use the following position settings:

Auto
Top of target
Bottom of target
Left of target
Right of target

The position setting specifies where the pin message renders relative to its target. If the target element's location is incompatible with the specified position, Amplitude tries a different location. For example, if the target is on the far-left side of the page, the pin can't render to the left. Amplitude then attempts to render the pin above, below, or to the right of the target. If the pin can't display in any of the four positions, Amplitude doesn't render the pin.

Click the three dot menu for the pin to access format settings.

Setting	Description
Open by default	Enables the pin to open without user interaction. If disabled, users must click or tap the pin to open it.
Open on hover	Opens the pin when the user hovers over the hotspot. Disable Open by default to use this setting. When Open by default is disabled and the Open on hover setting is also disabled, users must click the hotspot to open the pin.
Show mask	Enables a background mask when the pin is open to help draw the user's focus.
Content layout	Updates the visual ordering of the guide's content.
Title and content alignment	Changes the alignment of the title and body text.
Actions bar	Updates the placement and layout of the guide's buttons.
Z-index	Specify a custom z-index value for the popover.
Text animation	Enables the pin's text to animate in with a typewriter effect.
Disable auto-advance on target click	When you enable this option, clicking on the target element doesn't advance the guide to the next step.
Skip if target not found	When you enable this option, the guide skips to the next step if it can't find the target element within `250ms` of the step becoming active. If the step is the last step and the guide skips it, the guide completes.
Advance trigger	Enables advancing the guide to another step when the user interacts with the element you specify.

Tooltips are available in the Tooltip template, and contain one step.

Tooltips are like pins, but reveal only when a user clicks, taps, or hovers over them. Use tooltips to give inline details about a feature while saving UI space.

Setting	Description
Content layout	Updates the visual ordering of the guide's content.
Title and content alignment	Changes the alignment of the title and body text.
Actions bar	Updates the placement and layout of the guide's buttons.
Z-index	Specify a custom z-index value for the popover.
Pointer	Select the style that relates the dialog to the marker.
Marker	Select the appearance of the marker that reveals the tooltip message.
Marker Width	Define the width of the tooltip's marker (icon/image) in pixels.
Text animation	Enables the tooltip's text to animate in with a typewriter effect.
Show on hover/click	Select the trigger that causes the tooltip message to appear.

Tooltips bypass cooldowns and remain visible even after a user completes them. For tooltip surveys, users can fill out the survey again as a new submission.

Banners are available in the Banner template, and contain one step.

Banners are full-width blocks that show on either the top or bottom of the page. Use banners for longer-term announcements, status updates, or time-sensitive promotions.

Banner display limitations

Banners can overlap existing content on your website even when using the Inline display style. Overlap happens when your site has conflicting CSS styles on the body element or other page elements. If changing the display style from Overlay to Inline doesn't resolve content overlap, conflicting CSS in the application prevents the banner from rendering in the intended position.

Use card embeds as a workaround

If banners aren't rendering as expected, try card embeds. Card embeds render content directly into your page's DOM as native elements, which reduces the chance of CSS conflicts. For example, you can configure a card embed as Prepend to children (first child) on <body>, which typically renders the card as the top element on the page.

Setting	Description
Sticky	Keeps the banner visible while the user scrolls.
Display style	Controls the way in which the banner interacts with the page's content. Mobile banners support overlay only.
Z-index	Specify a custom z-index value for the popover.
Text animation	Enables the banner's text to animate in with a typewriter effect.

Checklist

Checklists provide a form that helps users track progress toward a goal. They contain one header and one or more checklist items. Use checklist items to trigger actions.

Setting	Description
Z-index	Specify a custom z-index value for the checklist.

Checklist items

Checklist items compose a checklist.

Setting	Description
Skippable	If enabled, the user can complete the checklist item via a "Skip" button.

Card embed

Card embeds render content directly into your page's DOM, embedding guides and surveys as native elements within your UI. Use card embeds for persistent content that should feel like part of your application rather than an overlay.

Card embeds require a target element selector that specifies where to place the card. Select from these position options to control how the card relates to the target element:

Position	Description
Append to children (last child)	Inserts the card as the last child element within the target.
Prepend to children (first child)	Inserts the card as the first child element within the target.
Before element	Places the card immediately before the target element.
After element	Places the card immediately after the target element.
Replace element	Replaces the target element with the card.
Width	Choose Auto to let the card size to its content, Fixed to specify a pixel width, or Full to fill the container width.
Alignment	When width isn't Full, align the card to the Left, Center, or Right of its container.
Height	Choose Auto to let the card size to its content, Fixed to specify a pixel height, or Full to fill the container height.
Margin	Set the top, right, bottom, and left margin (in pixels) to control spacing between the card and surrounding UI elements. Margin differs from padding: margin controls external spacing around the card, while padding controls internal spacing within the card.

Click the three dot menu to access format settings.

Setting	Description
Content layout	Updates the visual ordering of the guide's content.
Title and content alignment	Changes the alignment of the title and body text.
Actions bar	Updates the placement and layout of the guide's buttons.
Z-index	Specify a custom z-index value for the card.
Text animation	Enables the card's text to animate in with a typewriter effect.

Element selector

When you configure guides with pins, tooltips, card embeds, or element-based triggers, you must specify which element on your page to target. The element selector helps you identify and target specific page elements.

How the element selector works

Amplitude's visual element selector automatically identifies the most stable CSS selector for the element you choose, so your guide continues to work even if minor page changes occur.

To use the visual selector:

Click Test and Preview in the guide builder.
Navigate to the page containing your target element.
Click the element you want to target.
Amplitude automatically generates a CSS selector for that element.

Selecting nested elements

To select nested elements (elements inside other elements), use the Alt key (Option key on Mac) while hovering over elements:

Click Test and Preview.
Hover over the parent element.
Hold the Alt/Option key.
Continue hovering to drill down into nested child elements.
Click to select the nested element you want.

Use this method to target specific elements within complex page structures, such as buttons within cards or icons within menus.

Override or provide your own selector

To specify your own selector or get more control, manually enter a CSS or XPath selector:

In the element selector field, paste your CSS selector or XPath expression.
Choose your selection strategy:
- CSS Selector: Standard CSS selector syntax (for example, #submit-button, .primary-cta).
- XPath: XPath expression for more complex targeting (for example, //button[@id='submit']).
Optionally, add fallback text that Amplitude uses if the selector doesn't find a match.
Test your selector with Test and Preview to confirm it targets the correct element.

Best practices for custom selectors

Use stable attributes like IDs or data attributes that are less likely to change.
Avoid selectors that depend on specific positioning (like :nth-child) unless necessary.
Test your selectors across different pages and screen sizes.
Add data attributes specifically for guide targeting to ensure reliability.
Use :is() to create flexible selectors that work across multiple similar elements.

Examples of custom selectors:

CSS Selector: .header-navigation > .menu-item:first-child
XPath: //div[@class='container']//button[contains(text(), 'Submit')]
CSS with multiple elements: :is([my-class="foo"],[my-class="bar"])

Amplitude supports most modern CSS selector features, including functional pseudo-classes like :is(), :not(), :nth-of-type(), and :where(), so you can create more expressive and flexible selectors.

Target elements in shadow DOM

The visual element selector can't cross into shadow DOM boundaries. To target elements inside a shadow DOM, copy the JS path from your browser's DevTools and paste it into the selector field:

Open DevTools and navigate to the Elements panel.
Locate the target element inside the shadow root.
Right-click the element and select Copy > Copy JS path.
Paste the JS path into the element selector field in the guide builder.

Amplitude resolves through shadow roots and attaches the guide correctly.

If the target element doesn't exist in the DOM when the step renders, the pinned step doesn't display. Guides and Surveys doesn't support virtual targeting or auto-skipping for missing anchor elements.

Requirements for placeholder elements

If you use a placeholder element to represent a shadow DOM component, ensure the element meets these requirements for the visual selector to detect it:

The element isn't set to display: none.
The element has non-zero dimensions (width and height).
The element doesn't have pointer-events: none.

If the visual selector still can't detect the element, use DevTools to copy the CSS selector or JS path and paste it into the selector field manually.

Properties

These properties apply across form factors, so you can customize your guide components. Options available for each property may differ across form factors.

Position

Position controls where the guide appears on screen.

Form factor	Options
Modal	Top right, top center, top left, right center, bottom right, bottom center, bottom left, left center, center.
Popover	Top right, top center, top left, right center, bottom right, bottom center, bottom left, left center, center.
Pins	Controls position of the pin relative to the target element. Select the position and the alignment of the guide. For example, Position: `Bottom of target` and Alignment: `Left` places the guide below the target element, and aligns the guide's left side with the target's left side.
Tooltip	Specify the side of the target element where the info marker appears. Add vertical or horizontal offset as necessary.
Banner	Top or bottom of the page. Set the Sticky option to keep the banner visible while the user scrolls. Choose the Display style: Inline to display the banner within the contents of the page, or Overlay to float the banner on top of the page contents.
Card embed	Controls position relative to the target element. Select from Append, Prepend, Before, After, or Replace. Configure Width (Auto, Fixed, or Full), Alignment (Left, Center, or Right) when width isn't Full, Height (Auto, Fixed, or Full), and Margin (top, right, bottom, and left in pixels) to control spacing around the card.
Checklist header	Bottom left or Bottom right, in relation to the page.

Steps

Use steps to create multi-step guides. Break down processes into smaller, actionable steps that guide users from start to finish.

Tooltips and Banners contain one step.

Blocks

Blocks let you make your guide more engaging. Add a Button CTA, an image, or a video. Blocks align automatically based on the form factor and alignment you set.

Buttons

When you add a button, you can choose what happens when users click or tap it. Both primary and secondary buttons support all actions, including conditional logic.

Action	Description
Visit link	Opens the specified website. For web guides and surveys, choose Same tab (opens in the current tab/screen), New tab (opens in a new browser tab), or Use router (uses your configured router; requires router configuration). For mobile guides and surveys, choose Open in In-App Browser (opens the link within your app), Open in Device Browser (opens in the device's default browser), or Use router.
Click/Tap element	Specify an element on the page that receives a click event when the user clicks the button in the guide.
Show guide	Launch another guide.
Show survey	Launch a survey.
Go back	Go to the previous step in the guide.
Go forward	Advance to the next step in the guide.
Go to step	Go to the specified step in the guide.
Evaluate conditional logic	Execute different actions based on user properties or survey responses. Create conditions to personalize the button's behavior for different users. Go to Conditional Logic for more information.
Run callback	Trigger a callback function defined in your Guides and Surveys instrumentation. For more information, go to Register a callback
Submit app store rating request	Prompt the user to rate your app using the native in-app flow (App Store for iOS and Google Play for Android). The SDK calls the native rating API (StoreKit for iOS, Play In-App Review for Android). If the native API call itself returns an error (for example, no valid scene or activity) and you provide the app identifier in the survey configuration, the request falls back to the platform's app store page. If the call succeeds but the platform chooses not to show the rating dialog (due to rate limits, user opt-out, or other platform restrictions), the survey dismisses silently without opening the store page.
Open AI Assistant	Open the AI Assistant interface.
Open Resource Center	Open the Resource Center.
Open Document	Open a specified document.

Apple and Google control their own native app review display and may override requests for review from your guide.

Mark step complete when

Only checklists have the Mark step complete when option. Amplitude marks a checklist step complete when one of the following activities occurs:

Button is clicked
Page is visited
Element is clicked
Event is tracked

For each option, the checklist step updates from "incomplete" to "complete" only if the action happens on the client while the checklist is visible. For example, if Amplitude tracks an event server side, or the event happens before the checklist is shown, the step isn't marked complete.

Image

Upload an image to include in your experience. The experience's layout determines the image's position.

Video

Paste the URL of a video (YouTube, Vimeo, Loom, Vidyard, or .MP4 file). Like images, layout determines the video's position.

Was this helpful?