Lets Tour

Dead simple React element Walk-Through package. Powered by Popper.js and @reactour/mask

Styling of popover is completely upto you!

We're in Beta, breaking changes to come 😘

Coded with ❤️ by owenjs

Demo

Install

1yarn add @owenjs/lets-tour

Usage

1import { TLetsTourStep, LetsTourProvider, useLetsTourContext } from "@owenjs/lets-tour";
2import { useMemo } from "react";
3
4/**
5 * Each step in the Tour
6 */
7const STEPS: TLetsTourStep[] = [
8  {
9    selector: `[data-tour-step="1"]`
10  },
11  {
12    selector: `[data-tour-step="2"]`
13  }
14];
15
16/**
17 * Popover component and Styling
18 */
19const Popover = () => {
20  const { currentStep, handleBack, handleNext } = useLetsTourContext();
21
22  const content = useMemo(() => {
23    switch (currentStep) {
24      case 0:
25        return "Step 1";
26      case 1:
27        return "Step 2";
28    }
29  }, [currentStep]);
30
31  return (
32    <div style={{ background: "#ffffff" }}>
33      {content}
34      <button onClick={handleBack}>Back</button>
35      <button onClick={handleNext}>Next</button>
36    </div>
37  );
38};
39
40/**
41 * Main app component
42 */
43const App = () => {
44  const { handleStartTour } = useLetsTourContext();
45
46  return (
47    <>
48      <div data-tour-step="1">Step 1 Item</div>
49      <div data-tour-step="2">Step 2 Item</div>
50
51      <button onClick={handleStartTour}>Open Tour</button>
52    </>
53  );
54};
55
56/**
57 * React Index File
58 */
59const Index = () => {
60  return (
61    <LetsTourProvider steps={STEPS} Component={Popover}>
62      <App />
63    </LetsTourProvider>
64  );
65};

Component API

ILetsTourProviderProps

1import { LetsTourProvider } from "@owenjs/lets-tour";
2
3const App = () => {
4  // ...
5  
6  return (
7    <LetsTourProvider {...ILetsTourProviderProps}>
8      {/* Rest of your React App! */}
9    </LetsTourProvider>
10  );
11};

isOpen?: boolean

Allow Tourer to be a controlled component
@default false

steps: TLetsTourStep[]

Each step in the Tour, see TLetsTourStep

Component: () => ReactNode

Component to render the popover

onOpen?: () => void

Fired whenever the Tour is opened

onClose?: () => void

Fired whenever the Tour is closed

onChange?: (isOpen: boolean) => void

Fired whenever the Tour Open or Closed state is changed
Allows the component to be controlled

isDismissible?: boolean

Should the Tour be dismissible by the user clicking on the backdrop?

maskPadding?: [number, number]

Padding around the Highlighted Area
@default [10, 10]

onBackdropClick?: MouseEventHandler<HTMLDivElement>

Event handler for user clicks on the Tour backdrop

onHighlightedAreaClick?: MouseEventHandler<SVGRectElement>

Event handler for user clicks on the Highlighted Area

backdropClassName?: string

ClassName for the Tour backdrop

highlightedAreaClassName?: string

ClassName for the highlighted area of the Tour

maskStyles?: Record

Styles for the Mask
Optionally extend the default styles using the base param

1type maskStyles = {
2  /**
3   * Styles for the Tour backdrop
4   * @param base default styles
5   */
6  backdrop?: (base: CSSProperties) => CSSProperties;
7  /**
8   * Styles for the Tour Highlighted Area
9   * @param base default styles
10   * @param props
11   * @param props.x x position of the Highlighted Area
12   * @param props.y y position of the Highlighted Area
13   * @param props.width width of the Highlighted Area
14   * @param props.height height of the Highlighted Area
15   */
16  highlightedArea?: (
17    base: CSSProperties,
18    props: {
19      x: number;
20      y: number;
21      width: number;
22      height: number;
23    }
24  ) => CSSProperties;
25};

TTourContext

1import { useLetsTourContext } from "@owenjs/lets-tour";
2
3const App = () => {
4  const { ... } = useLetsTourContext();
5  
6  // ...
7};

steps: TLetsTourStep[]

Each step in the Tour, see TLetsTourStep

isOpen: boolean

Open state of the Tour

setIsOpen: Dispatch<SetStateAction<boolean>>

Set state for the open state of the Tour

currentStep: number

Current step of the Tour (starting at 0)

setCurrentStep: Dispatch<SetStateAction<number>>

Set state for the current step of the Tour (starting at 0)

handleStartTour: () => void

Start the Tour programmatically

handleEndTour: () => void

End the Tour programmatically

handleBack: () => void

Go back a step in the Tour

handleNext: () => void

Go forward a step in the Tour

TLetsTourStep

selector: string

CSS selector use to position of the Tour Popover

placement?: Placement

Placement of Tour Popover around selected element
@default auto

offset?: [number, number]

Offset the Tour Popper
@default [0, 20]