Tour
The tour components provided by EUI allow for a flexible and customizable way to showcase items on a page in an ordered manner by augmenting existing elements on the page without altering functionality.
Examples on this page use localStorage to persist state.
Usage
Wrap target element
The EuiTourStep component is the base for building a feature tour or an individual popover for onboarding.
All content and actions including titles, headings, and buttons are customizable via props.
Anchor to DOM element
Instead of wrapping the target element, use the anchor prop to specify a DOM node. Accepted values include an HTML element reference, a function returning an HTML element, or a CSS selector string such as anchor="#anchorTarget".
Guided tour
Uers proceed through tour steps without needing to complete actions on the underlying page. In this scenario, consider showing both Close tour and Next buttons.
Standalone steps
Each EuiTourStep can be configured independently via props. In this case, each component is stateless and needs to be paired with some form of state management for navigation. The later examples showcase other ways to handle state management via useEuiTour and EuiTour.
useEuiTour hook
The useEuiTour hook provides minimal state management using a predefined React reducer. Pass an array of steps consisting of accepted props, and an object of global configuration. The result is a full configuration object for each step, a set of reducer actions to perform state changes, and an up-to-date state object derived from the internal reducer.
EuiTour render prop component
The EuiTour render prop component provides minimal state management. An alternative to the useEuiTour hook, EuiTour can be used for React class components and use cases with a single wrapping component.
Tour demo
A complete tour set in a more realistic application UI. Unlike other examples on this page, the demo does not use localStorage to persist state.
My app
Guidelines
This page documents best practices for tour design including content, length and use cases.
When to use tours
Use tours when you want users to learn about specific UI elements and how interacting with them will help them achieve a goal. When you want to help users perform an action but don't want to provide step by step guidance, you can use empty states instead as seen in EuiEmptyPrompt.
For certain users, product tours can feel intrusive so first assess the fit for your use case and users. The goal is for the product tour to be a tool that helps the user learn new things and accomplish their goals. Three good scenarios for using a product tour are:
- New users seeing an interface for the first time.
- Novice users trying to gain proficiency in your application.
- Existing users need to be onboarded when new features or redesigns are released.
Additionally, consider asking users if they're interested in checking out your product tour instead of just showing it to them.
Provide concise yet valuable information
If you include information that is too obvious or basic, it is more likely that the user will dismiss the product tour and start perceiving them as low value. If further explanation is needed, consider linking out to documentation.
Do: Keep the content of each step short while making sure to provide useful information.
Don't: Use lengthy text that contains a lot of detail. Instead you can add a link for users to learn more.
Explain why the actions you want users to perform are useful
If users see value in an action they'll be more likely to engage.
Keep the tone conversational and friendly
Good copy is a key element for a product tour's success. Make sure you work alongside a writer in this process.
Allow users to end and restart the tour at any time
You can include a “Skip tour” button in your step's footer. Users might be quick to dismiss a tour but realize they need to use it later on. Give them the option to re-trigger the tour at any time. A good spot for a tour's trigger is the application's help menu.
Keep your tours short
The more steps, the less likely it is that a user will complete a tour. If you need to decide which steps to drop, think of the ones the user is more likely to be able to figure out on their own.
Be careful when using action-driven tours
Tours where one step cannot be completed until the previous step has been completed can lead to the user feeling trapped. A nice detail when using this type of tours is to automatically take the user to the next step upon completion of the current step, instead of having to click on Next.
Consider using animation gifs
A short, nicely crafted animation can be very effective for teaching a user about a feature.
Props
EuiTourStep
Prop | Description and type | Default value |
|---|---|---|
content# | Contents of the tour step popover ReactNode | Required |
onFinish# | Function to call for 'Skip tour' and 'End tour' actions NoArgCallback<void> | Required |
stepsTotal# | The total number of steps in the tour number | Required |
title# | Larger title text specific to this step. The title gets wrapped in the appropriate heading level. ReactNode | Required |
className# | Type: string | |
aria-label# | Provide a name to the popover panel string | |
data-test-subj# | Type: string | |
css# | Type: Interpolation<Theme> | |
zIndex# | By default, popover content inherits the z-index of the anchor number | |
children# | Element to which the tour step popover attaches when open ReactNode & ReactElement<any, string | JSXElementConstructor<any>> | |
aria-labelledby# | Alternative option to string | |
container# | Restrict the popover's position within this element HTMLElement | |
display# | CSS display type for both the popover and anchor Display | |
offset# | Distance away from the anchor that the popover will render number | |
panelRef# | Type: RefCallback<HTMLElement> | |
ownFocus# | Traps tab focus within the popover contents boolean | |
focusTrapProps# | Object of props passed to EuiFocusTrap Partial<EuiFocusTrapProps> | |
isOpen# | Visibility state of the popover boolean | |
repositionOnScroll# | When boolean | |
anchorPosition# | Alignment of the popover and arrow relative to the button "upCenter" | "upLeft" | "upRight" | "downCenter" | "downLeft" | "downRight" | "leftCenter" | "leftUp" | "leftDown" | "rightCenter" | "rightUp" | "rightDown" | leftUp |
attachToAnchor# | Style and position alteration for arrow-less attachment. boolean | |
hasArrow# | Show arrow indicating to originating button boolean | |
initialFocus# | Specifies what element should initially have focus; Can be a DOM If not passed, initial focus defaults to the popover panel. ElementTarget | |
insert# | Passed directly to EuiPortal for DOM positioning. Both properties are { sibling: HTMLElement; position: "before" | "after"; } | |
panelClassName# | Custom class added to the EuiPanel containing the popover contents string | |
panelPaddingSize# | EuiPanel padding on all sides "xs" | "s" | "m" | "l" | "xl" | "none" | |
panelStyle# | Standard DOM CSSProperties | |
panelProps# | Object of props passed to EuiPanel. See #EuiPopoverPanelProps Omit<_EuiPanelDivlike, "style" | "color" | "hasBorder" | "hasShadow"> | |
popoverScreenReaderText# | Optional screen reader instructions to announce upon popover open, ReactNode | |
popoverRef# | Type: Ref<HTMLDivElement> | |
repositionToCrossAxis# | By default, popovers will attempt to position themselves along the initial If you do not not want this repositioning to occur (and it is acceptable for boolean | true |
buffer# | Minimum distance between the popover and the bounding container; number | [number, number, number, number] | 16 |
arrowChildren# | Element to pass as the child element of the arrow; ReactNode | |
onPositionChange# | Function callback for when the popover positon changes (position: EuiPopoverPosition) => void | |
closePopover# | Callback to handle hiding of the popover NoArgCallback<void> | () => {} |
anchor# | Selector or reference to the element to which the tour step popover attaches when open ElementTarget | |
isStepOpen# | Step will display if set to boolean | false |
minWidth# | Change the default min width of the popover panel MinWidth<string | number> | 300 |
maxWidth# | Change the default max width of the popover panel MaxWidth<string | number> | 600 |
step# | The number of the step within the parent tour. 1-based indexing. number | 1 |
subtitle# | Smaller title text that appears atop each step in the tour. The subtitle gets wrapped in the appropriate heading level. ReactNode | |
decoration# | Extra visual indication of step location "none" | "beacon" | beacon |
footerAction# | Accepts any ReactNode | ReactNode[] |