Tour props

Properties to customize the Tour

steps?

Type: StepType[]

Array of elements to highlight with special info and props.

components?

Type: PopoverComponentsType

Customize granurally each Component inside the Popover.

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.

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.

position?

Type: Position

Set the global position value for the Popover in all steps

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.

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.

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.

<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>

keyboardHandler?

Type: KeyboardHandler

Function to handle keyboard events in a custom way.

<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.

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.

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.

ContentComponent?

Type: ComponentType<PopoverContentProps>

Completelly custom component to render inside the Popover.

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).