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.
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 |
|---|---|---|
Prop content# | Description and type Contents of the tour step popover ReactNode | Default value Required |
Prop onFinish# | Description and type Function to call for 'Skip tour' and 'End tour' actions NoArgCallback<void> | Default value Required |
Prop stepsTotal# | Description and type The total number of steps in the tour number | Default value Required |
Prop title# | Description and type Larger title text specific to this step. The title gets wrapped in the appropriate heading level. ReactNode | Default value Required |
Prop className# | Description and type Type: string | Default value |
Prop aria-label# | Description and type Provide a name to the popover panel string | Default value |
Prop data-test-subj# | Description and type Type: string | Default value |
Prop css# | Description and type Type: Interpolation<Theme> | Default value |
Prop zIndex# | Description and type By default, popover content inherits the z-index of the anchor number | Default value |
Prop children# | Description and type Element to which the tour step popover attaches when open ReactNode & ReactElement<any, string | JSXElementConstructor<any>> | Default value |
Prop aria-labelledby# | Description and type Alternative option to string | Default value |
Prop container# | Description and type Restrict the popover's position within this element HTMLElement | Default value |
Prop display# | Description and type CSS display type for both the popover and anchor Display | Default value |
Prop offset# | Description and type Distance away from the anchor that the popover will render number | Default value |
Prop panelRef# | Description and type Type: RefCallback<HTMLElement> | Default value |
Prop ownFocus# | Description and type Traps tab focus within the popover contents boolean | Default value |
Prop focusTrapProps# | Description and type Object of props passed to EuiFocusTrap Partial<EuiFocusTrapProps> | Default value |
Prop isOpen# | Description and type Visibility state of the popover boolean | Default value |
Prop repositionOnScroll# | Description and type When boolean | Default value |
Prop anchorPosition# | Description and type Alignment of the popover and arrow relative to the button "upCenter" | "upLeft" | "upRight" | "downCenter" | "downLeft" | "downRight" | "leftCenter" | "leftUp" | "leftDown" | "rightCenter" | "rightUp" | "rightDown" | Default value leftUp |
Prop attachToAnchor# | Description and type Style and position alteration for arrow-less attachment. boolean | Default value |
Prop hasArrow# | Description and type Show arrow indicating to originating button boolean | Default value |
Prop initialFocus# | Description and type Specifies what element should initially have focus; Can be a DOM If not passed, initial focus defaults to the popover panel. ElementTarget | Default value |
Prop insert# | Description and type Passed directly to EuiPortal for DOM positioning. Both properties are { sibling: HTMLElement; position: "before" | "after"; } | Default value |
Prop panelClassName# | Description and type Custom class added to the EuiPanel containing the popover contents string | Default value |
Prop panelPaddingSize# | Description and type EuiPanel padding on all sides "xs" | "s" | "m" | "l" | "xl" | "none" | Default value |
Prop panelStyle# | Description and type Standard DOM CSSProperties | Default value |
Prop panelProps# | Description and type Object of props passed to EuiPanel. See #EuiPopoverPanelProps Omit<_EuiPanelDivlike, "style" | "color" | "hasBorder" | "hasShadow"> | Default value |
Prop popoverScreenReaderText# | Description and type Optional screen reader instructions to announce upon popover open, ReactNode | Default value |
Prop popoverRef# | Description and type Type: Ref<HTMLDivElement> | Default value |
Prop repositionToCrossAxis# | Description and type 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 | Default value true |
Prop buffer# | Description and type Minimum distance between the popover and the bounding container; number | [number, number, number, number] | Default value 16 |
Prop arrowChildren# | Description and type Element to pass as the child element of the arrow; ReactNode | Default value |
Prop onPositionChange# | Description and type Function callback for when the popover positon changes (position: EuiPopoverPosition) => void | Default value |
Prop closePopover# | Description and type Callback to handle hiding of the popover NoArgCallback<void> | Default value () => {} |
Prop anchor# | Description and type Selector or reference to the element to which the tour step popover attaches when open ElementTarget | Default value |
Prop isStepOpen# | Description and type Step will display if set to boolean | Default value false |
Prop minWidth# | Description and type Change the default min width of the popover panel MinWidth<string | number> | Default value 300 |
Prop maxWidth# | Description and type Change the default max width of the popover panel MaxWidth<string | number> | Default value 600 |
Prop step# | Description and type The number of the step within the parent tour. 1-based indexing. number | Default value 1 |
Prop subtitle# | Description and type Smaller title text that appears atop each step in the tour. The subtitle gets wrapped in the appropriate heading level. ReactNode | Default value |
Prop decoration# | Description and type Extra visual indication of step location "none" | "beacon" | Default value beacon |
Prop footerAction# | Description and type Accepts any ReactNode | ReactNode[] | Default value |
EuiTourStepIndicator
Prop | Description and type | Default value |
|---|---|---|
Prop number# | Description and type Type: number | Default value Required |
Prop status# | Description and type Type: EuiTourStepStatus | Default value Required |
Prop className# | Description and type Type: string | Default value |
Prop aria-label# | Description and type Type: string | Default value |
Prop data-test-subj# | Description and type Type: string | Default value |
Prop css# | Description and type Type: Interpolation<Theme> | Default value |