Tour
Tour Props

Tour props

Properties to customize the Tour

steps?

Type: StepType[]

Array of elements to highlight with special info and props.

StepType
OptionTypeDescription
selectorstring | ElementA string containing one CSS Selector to match and highlight the element at the time of this step.
contentstring | ({ setCurrentStep, transition, isHighlightingObserved, currentStep, setIsOpen }) => voidThe content to show inside the Popover at the time of this step. Using a function, there are parameters with values, available to use as content.
position?'top' | 'right' | 'bottom' | 'left' | 'center' | [number, number]The preferred postion to position the Popover in relation with the highlighted element. Will be automatically calculated in case of unavailable space.
highlightedSelectors?string[]Array of CSS Selector to be included (by union) in the highlighted region of the Mask
mutationObservables?string[]Array of CSS Selector that when resizeing each will triggered a rerender of the Mask shape
navDotAriaLabel?stringString to assign to `aria-label` attribute of the Dot button relative of this step in the navigation.
stepInteraction?booleanAllow to reenable the interaction for this specific step, when `disableInteraction` (from `TourProvider`) is `true`
action?(elem: Element | null) => voidAction fired as soon as Tour arrives in this step.
actionAfter?(elem: Element | null) => voidAction fired as soon as Tour leaves this step.
disableActions?booleanDisable all possible actions when the Tour is in this step.
padding?PaddingControl padding spaces for this specific step.
bypassElem?booleanExcludes the main `selector` when calculating highlited area if present `highlightedSelectors`.
styles?StylesObj & PopoverStylesObj & MaskStylesObjCustomize styles fro this specific step.

components?

Type: PopoverComponentsType

Customize granurally each Component inside the Popover.

Components

Available Components and its props

OptionTypeDescription
Badgestyles
Closestyles, onClick, disabled
Contentcontent,setCurrentStep,transition, isHighlightingObserved,currentStep,setIsOpen
Navigationstyles,setCurrentStep, steps, currentStep, disableDots, nextButton, prevButton, setIsOpen, hideButtons, hideDots, disableAll, rtl, Arrow
Arrowstyles, inverted, disabled
Exmple
import { components } from "@react-explore-kit/tour";
 
function Badge({ children }) {
  return (
    <components.Badge
      styles={{ badge: (base) => ({ ...base, backgroundColor: "red" }) }}
    >
      👉 {children} 👈
    </components.Badge>
  );
}
 
function Close({ onClick }) {
  return (
    <button
      onClick={onClick}
      style={{ position: "absolute", right: 0, top: 0 }}
    >
      x
    </button>
  );
}
 
const steps = [
  /* ... */
];
 
export default function App() {
  return (
    <TourProvider steps={steps} components={{ Badge, Close }}>
      {/* ... */}
    </TourProvider>
  );
}

styles?

Type: StylesObj & PopoverStylesObj & MaskStylesObj

Prop to customize styles for the different parts of the Mask, Popover and Tour using a function that allows to extend the base styles an take advantage of some state props.

StylesObj

Styles keys and its props available to customize. Refer to Mask docs and Popover docs for its specific styles keys

OptionTypeDescription
badge
controls
buttondisabled
arrowdisabled
dotcurrent, disabled, showNumber
closedisabled
Example
const styles = {
  maskWrapper: (base) => ({
    ...base,
    color: "red",
  }),
  highlightedArea: (base, { x, y }) => ({
    ...base,
    x: x + 10,
    y: y + 10,
  }),
  badge: (base) => ({ ...base, color: "blue" }),
};
 
function App() {
  return <TourProvider styles={styles} />;
}

padding?

Type: Padding

Extra space to add between the Mask and the Popover and the highlighted element. A single number coordinates both spaces. Otherwise, passing an Object specifying the Component space.

Padding

Type: number | { mask?: ComponentPadding, popover?: ComponentPadding, wrapper?: ComponentPadding }

ComponentPadding

Calculation is based on padding shorthand syntax (opens in a new tab)

OptionTypeDescription
valuenumberApply to all four sides`
[x, y]number[]top and bottom | left and right
[top, x, bottom]number[]top | left and right | bottom
[top, right, bottom, left]number[]top | right | bottom | left

position?

Type: Position

Set the global position value for the Popover in all steps

Position

Type: 'top' | 'right' | 'bottom' | 'left' | 'center' | [number, number] | ((postionsProps: PositionProps, prevRect: RectResult) => Position)

Fixed in case of [number, number], calculated prefered position in case of string.

PositionProps
OptionTypeDescription
bottomnumber
heightnumber
leftnumber
rightnumber
topnumber
widthnumber
windowWidthnumber
windowHeightnumber

setCurrentStep?

Type: Dispatch<React.SetStateAction<number>>

Function to control the Tour current step state.

currentStep?

Type: number

Custom Tour current step state.

disableInteraction?

Type: boolean | ((clickProps: Pick<ClickProps, 'currentStep' | 'steps' | 'meta'>) => boolean)

Disables the ability to click or interact in any way with the Highlighted element on every step.

This option can be overrided on specific steps using stepInteraction prop.

disableFocusLock?

Type: boolean

The Tour uses FocusScope (opens in a new tab) in order to lock the focus iteration inside the Popover when Tour is active. This prop disables this behaviour.

disableDotsNavigation?

Type: boolean

Disable interactivity with Dot navigation inside Popover.

disableWhenSelectorFalsy?

Type: boolean

If true, don't show tours when selector or document.getElementById(step.selector) is falsy.

disableKeyboardNavigation?

Type: boolean | KeyboardParts[]

Default: false

Disable all keyboard navigation events when true, disable only selected keys when array.

KeyboardParts

Type: 'esc' | 'left' | 'right'

className?

Type: string

Default: react-explore-kit__popover

CSS classname (opens in a new tab) assigned to the Popover

maskClassName?

Type: string

Default: react-explore-kit__mask

CSS classname (opens in a new tab) assigned to the Mask

highlightedMaskClassName?

Type: string

Default: react-explore-kit__mask

CSS classname (opens in a new tab) assigned to highlighted part of the Mask. Useful when using disableInteraction.

nextButton?

Type: (props: BtnFnProps) => void

Helper functions to customize the Next button inside Popover, with useful parameters. It is possible to use the base Button and customize the props.

prevButton?

Type: (props: BtnFnProps) => void

Helper functions to customize the Prev button inside Popover, with useful parameters. It is possible to use the base Button and customize the props.

BtnFnProps
OptionTypeDescription
ButtonReact.FC<NavButtonProps>
setCurrentStepDispatch<React.SetStateAction<number>>
stepsLengthnumber
currentStepnumber
setIsOpenDispatch<React.SetStateAction<Boolean>>
NavButtonProps
OptionTypeDescription
onClick?() => void
kind?'next' | 'prev'
hideArrow?boolean

afterOpen?

Type: (target: Element | null) => void

Action fired just after the Tour is open.

beforeClose?

Type: (target: Element | null) => void

Action fired just before the Tour is closed.

onClickMask?

Type: (clickProps: ClickProps) => void

Function that overrides the default close behavior of the Mask click handler. Comes with useful parameters to play with.

onClickClose?

Type: (clickProps: ClickProps) => void

Function that overrides the default close behavior of the Close icon click handler. Comes with useful parameters to play with.

onClickHighlighted?

Type: (e: MouseEventHandler<SVGRectElement>, clickProps: ClickProps) => void

Click handler for highlighted area. Only works when disableInteraction is active.

Useful in case is needed to avoid onClickMask when clicking the highlighted element.

Exmple
<TourProvider
  steps={steps}
  disableInteraction
  onClickHighlighted={(e, clickProps) => {
    console.log("No interaction at all");
    if (clickProps.currentStep < 2) {
      e.stopPropagation();
      event.preventDefault();
      clickProps.setCurrentStep(
        Math.min(clickProps.currentStep + 1, clickProps.steps.length - 1)
      );
    }
  }}
>
  {/* ... */}
</TourProvider>
ClickProps
OptionTypeDescription
setIsOpenDispatch<React.SetStateAction<Boolean>>
setCurrentStepDispatch<React.SetStateAction<number>>
setStepsDispatch<React.SetStateAction<StepType[]>>
setMetaDispatch<React.SetStateAction<string>>
currentStepnumber
stepsStepType[]
metastring

keyboardHandler?

Type: KeyboardHandler

Function to handle keyboard events in a custom way.

KeyboardHandler

Type: (e: KeyboardEvent, clickProps?: ClickProps, status?: { isEscDisabled?: boolean, isRightDisabled?: boolean, isLeftDisabled?: boolean }) => void

Exmple
<TourProvider
  steps={steps}
  disableInteraction
  keyboardHandler={(e, clickProps) => {
    if (e.key === "ArrowRight") {
      clickProps.setCurrentStep(
        Math.min(clickProps.currentStep + 1, clickProps.steps.length - 1)
      );
    }
    if (e.key === "ArrowLeft") {
      clickProps.setCurrentStep(Math.max(clickProps.currentStep - 1, 0));
    }
    if (e.key === "Escape") {
      const nextStep = Math.floor(Math.random() * clickProps.steps.length);
      clickProps.setCurrentStep(nextStep);
    }
  }}
>
  {/* ... */}
</TourProvider>

badgeContent?

Type: (badgeProps: BadgeProps) => any

Function to customize the content of the Badge using helper parameters like the current and total steps and if the Tour is transitioning between steps.

BadgeProps
OptionTypeDescription
totalStepsnumber
currentStepnumber
transitionboolean

showNavigation?

Type: boolean

Show or hide the Navigation (Prev and Next buttons and Dots) inside Popover.

showPrevNextButtons?

Type: boolean

Show or hide Prev and Next buttons inside Popover.

showCloseButton?

Type: boolean

Show or hide the Close button inside Popover.

showBadge?

Type: boolean

Show or hide the Badge inside Popover.

showDots?

Type: boolean

Show or hide dots navigation inside Popover.

scrollSmooth?

Type: boolean

Activate smooth scroll behavior when steps are outside viewport.

inViewThreshold?

Type: { x?: number, y?: number } | number

Tolerance in pixels to add when calculating if the step element is outside viewport to scroll into view.

accessibilityOptions?

Type: A11yOptions

Configure generic accessibility related attributes like aria-labelledby (opens in a new tab), aria-label (opens in a new tab) for Close button and if show or hide Dot navigation in screen readers.

A11yOptions
OptionTypeDescription
ariaLabelledBystring
closeButtonAriaLabelnumber
showNavigationScreenReadersboolean

rtl?

Type: boolean

Option to navigate and show Navigation in right-to-left mode

maskId?

Type: string

String to be assigned to the <mask /> element (otherwise an automatic unique id) of Mask Component

clipId?

Type: string

String to be assigned to the <clipPath /> element (otherwise an automatic unique id) of Mask Component

onTransition?

Type: PositionType

Function to control the behavior of Popover when is transitioning/scrolling from one step to another, calculating with Popover next position and previous one.

PositionType

Type: (postionsProps: PositionProps, prev: RectResult) => 'top' | 'right' | 'bottom' | 'left' | 'center' | [number, number]

ContentComponent?

Type: ComponentType<PopoverContentProps>

Completelly custom component to render inside the Popover.

PopoverContentProps
OptionTypeDescription
styles?StylesObj & PopoverStylesObj & MaskStylesObj
badgeContent?(badgeProps: BadgeProps) => any
components?PopoverComponentsType
accessibilityOptions?A11yOptions
disabledActions?boolean
onClickClose?boolean
setCurrentStep?Dispatch<React.SetStateAction<number>>
currentStepnumber
transition?boolean
isHighlightingObserved?boolean
setIsOpenDispatch<React.SetStateAction<Boolean>>
stepsStepType[]
showNavigation?boolean
showPrevNextButtons?boolean
showCloseButton?boolean
showBadge?boolean
nextButton?(props: BtnFnProps) => void
prevButton?(props: BtnFnProps) => void
disableDotsNavigation?boolean
rtl?boolean
Exmple
function ContentComponent(props) {
  const isLastStep = props.currentStep === props.steps.length - 1;
  const content = props.steps[props.currentStep].content;
  return (
    <div style={{ border: "5px solid red", padding: 10, background: "white" }}>
      {/* Check if the step.content is a function or a string */}
      {typeof content === "function"
        ? content({ ...props, someOtherStuff: "Custom Text" })
        : content}
      <button
        onClick={() => {
          if (isLastStep) {
            props.setIsOpen(false);
          } else {
            props.setCurrentStep((s) => s + 1);
          }
        }}
      >
        {isLastStep ? "x" : ">"}
      </button>
    </div>
  );
}
 
const steps = [
  /* ... */
];
 
function App() {
  return (
    <TourProvider
      steps={steps}
      ContentComponent={ContentComponent}
      styles={{ popover: (base) => ({ ...base, padding: 0 }) }}
    >
      {/* ... */}
    </TourProvider>
  );
}

Wrapper?

Type: ComponentType

Default: React.Fragment

Element which wraps the Tour. Useful in case is needed to port the Tour into a Portal (opens in a new tab).