Skip to main content

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:

  1. New users seeing an interface for the first time.
  2. Novice users trying to gain proficiency in your application.
  3. 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.

concise content in tour step

Do: Keep the content of each step short while making sure to provide useful information.

lengthy content in tour step

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.

Adjust your tour based on UX research

Once your tour goes live, monitor user behavior to learn about what's working and identify drop-off points. Based on that, iterate on your tour.

Consider using animation gifs

A short, nicely crafted animation can be very effective for teaching a user about a feature.

skip tour button

Props

EuiTourStep

This table contains 43 rows.
Prop
Description and type
Default value
content#

Contents of the tour step popover

Type: ReactNode
Required
onFinish#

Function to call for 'Skip tour' and 'End tour' actions

Type: NoArgCallback<void>
Required
stepsTotal#

The total number of steps in the tour

Type: number
Required
title#

Larger title text specific to this step. The title gets wrapped in the appropriate heading level.

Type: ReactNode
Required
className#
Type: string
aria-label#

Provide a name to the popover panel
Defines a string value that labels the current element.
@see aria-labelledby.

Type: string
data-test-subj#
Type: string
css#
Type: Interpolation<Theme>
zIndex#

By default, popover content inherits the z-index of the anchor
component; pass zIndex to override

Type: number
children#

Element to which the tour step popover attaches when open

Type: ReactNode & ReactElement<any, string | JSXElementConstructor<any>>
aria-labelledby#

Alternative option to aria-label that takes an id.
Usually takes the id of the popover title
Identifies the element (or elements) that labels the current element.
@see aria-describedby.

Type: string
container#

Restrict the popover's position within this element

Type: HTMLElement
display#

CSS display type for both the popover and anchor

Type: Display
offset#

Distance away from the anchor that the popover will render

Type: number
panelRef#
Type: RefCallback<HTMLElement>
ownFocus#

Traps tab focus within the popover contents

Type: boolean
focusTrapProps#

Object of props passed to EuiFocusTrap

Type: Partial<EuiFocusTrapProps>
isOpen#

Visibility state of the popover

Type: boolean
repositionOnScroll#

When true, the popover's position is re-calculated when the user
scrolls, this supports having fixed-position popover anchors. When nesting
an EuiPopover in a scrollable container, repositionOnScroll should be true

Type: boolean
anchorPosition#

Alignment of the popover and arrow relative to the button

Type: "upCenter" | "upLeft" | "upRight" | "downCenter" | "downLeft" | "downRight" | "leftCenter" | "leftUp" | "leftDown" | "rightCenter" | "rightUp" | "rightDown"
leftUp
attachToAnchor#

Style and position alteration for arrow-less attachment.
Intended for use with inputs as anchors, e.g. EuiInputPopover

Type: boolean
hasArrow#

Show arrow indicating to originating button

Type: boolean
initialFocus#

Specifies what element should initially have focus; Can be a DOM
node, or a selector string (which will be passed to
document.querySelector() to find the DOM node), or a function that
returns a DOM node.

If not passed, initial focus defaults to the popover panel.

Type: ElementTarget
insert#

Passed directly to EuiPortal for DOM positioning. Both properties are
required if prop is specified

Type: { sibling: HTMLElement; position: "before" | "after"; }
panelClassName#

Custom class added to the EuiPanel containing the popover contents

Type: string
panelPaddingSize#

EuiPanel padding on all sides

Type: "xs" | "s" | "m" | "l" | "xl" | "none"
panelStyle#

Standard DOM style attribute. Passed to the EuiPanel

Type: CSSProperties
panelProps#

Object of props passed to EuiPanel. See #EuiPopoverPanelProps

Type: Omit<_EuiPanelDivlike, "style" | "color" | "hasBorder" | "hasShadow">
popoverScreenReaderText#

Optional screen reader instructions to announce upon popover open,
in addition to EUI's default popover instructions for Escape on close.
Useful for popovers that may have additional keyboard capabilities such as
arrow navigation.

Type: ReactNode
popoverRef#
Type: Ref<HTMLDivElement>
repositionToCrossAxis#

By default, popovers will attempt to position themselves along the initial
axis specified. If there is not enough room either vertically or horizontally
however, the popover will attempt to reposition itself along the secondary
cross axis if there is room there instead.

If you do not not want this repositioning to occur (and it is acceptable for
the popover to appear offscreen), set this to false to disable this behavior.

Type: boolean
true
buffer#

Minimum distance between the popover and the bounding container;
Pass an array of 4 values to adjust each side differently: [top, right, bottom, left]

Type: number | [number, number, number, number]
16
arrowChildren#

Element to pass as the child element of the arrow;
Use case is typically limited to an accompanying EuiBeacon

Type: ReactNode
onPositionChange#

Function callback for when the popover positon changes

Type: (position: EuiPopoverPosition) => void
closePopover#

Callback to handle hiding of the popover

Type: NoArgCallback<void>
() => {}
anchor#

Selector or reference to the element to which the tour step popover attaches when open

Type: ElementTarget
isStepOpen#

Step will display if set to true

Type: boolean
false
minWidth#

Change the default min width of the popover panel

Type: MinWidth<string | number>
300
maxWidth#

Change the default max width of the popover panel

Type: MaxWidth<string | number>
600
step#

The number of the step within the parent tour. 1-based indexing.

Type: number
1
subtitle#

Smaller title text that appears atop each step in the tour. The subtitle gets wrapped in the appropriate heading level.

Type: ReactNode
decoration#

Extra visual indication of step location

Type: "none" | "beacon"
beacon
footerAction#

Accepts any ReactNode to replace the 'Skip tour' link in the footer.
Ideally, pass one button or an array of up to 2 buttons.

Type: ReactNode | ReactNode[]

EuiTourStepIndicator

This table contains 6 rows.
Prop
Description and type
Default value
number#
Type: number
Required
status#
Type: EuiTourStepStatus
Required
className#
Type: string
aria-label#
Type: string
data-test-subj#
Type: string
css#
Type: Interpolation<Theme>

EuiTour

This table contains 2 rows.
Prop
Description and type
Default value
steps#
Type: EuiStatelessTourSteps
Required
initialState#
Type: EuiTourState
Required