Tour Navigator

Tour Navigator is a React package designed to facilitate the creation of customizable tours for React websites.

Installation

To install Tour Navigator, you can use npm or yarn:

npm install tour-navigator 
# or 
yarn add tour-navigator

Usage

import TourNavigator from 'tour-navigator';
import { Align, Position } from "tour-navigator/lib/TourNavigator/types";

// Define your steps
const steps = [
  {
    selector: '.step1',
    data: { /* Step data */ },
    position: Position.LEFT,
    align: Align.START
  },
  {
    selector: '.step2',
    data: { /* Step data */ },
    position: Position.BOTTOM,
    align: Align.CENTER
  },
  // Add more steps as needed
];

// Set up Tour Navigator with your steps
<TourNavigator
  id="my-tour"
  steps={steps}
/>

Demo

Check out the live demo here.

CodeSandbox Example

For a live interactive example, you can check out this CodeSandbox.

| Prop | Type | Description | Default | |------------------------|----------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|------------------------------| | id | string | Unique identifier for the tour. | ___tournavigator-${Date.now()} | | maskRadius | number | Radius of the mask around highlighted elements. | 5 | | maskPadding | number | Padding around the mask. | 5 | | maskOpacity | number | Opacity of the mask. | 1 | | maskStyle | CSSProperties | Custom CSS styles for the mask. | | | maskStyleDuringScroll | CSSProperties | Custom CSS styles for the mask during scroll. | | | startAt | number | Index of the step to start the tour at. | 0 | | maskHelperDistance | number | Distance between the mask and the helper element. | 10 | | screenHelperDistance | number | Distance between the screen and the helper element. | 10 | | onAfterOpen | (() => void) | null | Callback function triggered after the tour starts. | null | | onBeforeClose | (() => void) | null | Callback function triggered before the tour ends. | null | | steps | Step[] | Array of steps defining the tour. | [] | | helper | ((props: HelperProps) => ReactNode) | null | Custom helper component for each step. | null | | isOpen | boolean | Flag to control the visibility of the tour. | true | | onRequestClose | ((params: {event: MouseEvent | PointerEvent, isMask: boolean, isOverlay: boolean}) => void) | null | Callback function triggered when the tour is closed. | null | | onNext | ((props: HelperProps) => void) | null | Callback function triggered when the "Next" button is clicked. | null | | onPrev | ((props: HelperProps) => void) | null | Callback function triggered when the "Prev" button is clicked. | null | | onMove | ((props: HelperProps) => void) | null | Callback function triggered when the tour moves to the next step. | null | | scrollBehavior | 'smooth' | 'auto' | Defines the scroll behavior when moving to a new step. | 'auto' | | resizeListener | boolean | Flag to enable/disable resize listener. | true | | scrollListener | boolean | Flag to enable/disable scroll listener. | true | | mutationObserve | MutationObserverConfig | Configuration for mutation observer to watch changes in DOM. | | | overlayFill | string | Fill color of the overlay. | 'black' | | overlayOpacity | number | Opacity of the overlay. | 0.5 | | overlay | ((props: OverlayProps) => ReactNode) | null | Custom overlay component. | null | | className | string | Custom CSS class for the Tour Navigator component. | | | style | CSSProperties | Custom CSS styles for the Tour Navigator component. | | | renderOverlay | boolean | Flag to enable/disable rendering of the overlay. | true | | renderHelper | boolean | Flag to enable/disable rendering of the helper component. | true | | renderElement | HTMLElement | string | The element in which the Tour Navigator will be rendered. | | | scrollingElement | HTMLElement | Document | Element | string | The element used for scrolling. | | | waitForElementRendered | boolean | Works only when mutationObserver provided, |

Step

 Tour Navigator

Tour Navigator is a React package designed to facilitate the creation of customizable tours for React websites.

## Installation

To install Tour Navigator, you can use npm or yarn:

```bash
npm install tour-navigator 
# or 
yarn add tour-navigator

Usage

import TourNavigator from 'tour-navigator';
import { Align, Position } from "tour-navigator/lib/TourNavigator/types";

// Define your steps
const steps = [
  {
    selector: '.step1',
    data: { /* Step data */ },
    position: Position.LEFT,
    align: Align.START
  },
  {
    selector: '.step2',
    data: { /* Step data */ },
    position: Position.BOTTOM,
    align: Align.CENTER
  },
  // Add more steps as needed
];

// Set up Tour Navigator with your steps
<TourNavigator
  id="my-tour"
  steps={steps}
/>

Demo

Check out the live demo here.

CodeSandbox Example

For a live interactive example, you can check out this CodeSandbox.

| Prop | Type | Description | Default | |------------------------|----------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|------------------------------| | id | string | Unique identifier for the tour. | ___tournavigator-${Date.now()} | | maskRadius | number | Radius of the mask around highlighted elements. | 5 | | maskPadding | number | Padding around the mask. | 5 | | maskOpacity | number | Opacity of the mask. | 1 | | maskStyle | CSSProperties | Custom CSS styles for the mask. | | | maskStyleDuringScroll | CSSProperties | Custom CSS styles for the mask during scroll. | | | startAt | number | Index of the step to start the tour at. | 0 | | maskHelperDistance | number | Distance between the mask and the helper element. | 10 | | screenHelperDistance | number | Distance between the screen and the helper element. | 10 | | onAfterOpen | (() => void) | null | Callback function triggered after the tour starts. | null | | onBeforeClose | (() => void) | null | Callback function triggered before the tour ends. | null | | steps | Step[] | Array of steps defining the tour. | [] | | helper | ((props: HelperProps) => ReactNode) | null | Custom helper component for each step. | null | | isOpen | boolean | Flag to control the visibility of the tour. | true | | onRequestClose | ((params: {event: MouseEvent | PointerEvent, isMask: boolean, isOverlay: boolean}) => void) | null | Callback function triggered when the tour is closed. | null | | onNext | ((props: HelperProps) => void) | null | Callback function triggered when the "Next" button is clicked. | null | | onPrev | ((props: HelperProps) => void) | null | Callback function triggered when the "Prev" button is clicked. | null | | onMove | ((props: HelperProps) => void) | null | Callback function triggered when the tour moves to the next step. | null | | scrollBehavior | 'smooth' | 'auto' | Defines the scroll behavior when moving to a new step. | 'auto' | | resizeListener | boolean | Flag to enable/disable resize listener. | true | | scrollListener | boolean | Flag to enable/disable scroll listener. | true | | mutationObserve | MutationObserverConfig | Configuration for mutation observer to watch changes in DOM. | | | overlayFill | string | Fill color of the overlay. | 'black' | | overlayOpacity | number | Opacity of the overlay. | 0.5 | | overlay | ((props: OverlayProps) => ReactNode) | null | Custom overlay component. | null | | className | string | Custom CSS class for the Tour Navigator component. | | | style | CSSProperties | Custom CSS styles for the Tour Navigator component. | | | renderOverlay | boolean | Flag to enable/disable rendering of the overlay. | true | | renderHelper | boolean | Flag to enable/disable rendering of the helper component. | true | | renderElement | HTMLElement | string | The element in which the Tour Navigator will be rendered. | | | scrollingElement | HTMLElement | Document | Element | string | The element used for scrolling. | | | waitForElementRendered | boolean | Works only when mutationObserver provided, |

Step

type IntersectionOption = {
  root?: Element | Document | string | null; // Default: null
  rootMargin?: string; // Default: dynamically adjusted
  threshold?: number; // Default: dynamically adjusted
}
  
type Step = {
  selector: string;
  align?: Align,
  position?: Position | [Position, Position, Position, Position];
  data: any,
  scrollIntoView?: boolean;  // Default: true (Whether scroll to view element or not)
  intersectionOption?: IntersectionOption | (intersectionOption: IntersectionOption) => IntersectionOption;
}

HelperProps

type HelperProps = {
    id?: string;
    currentStep: Step | null;
    target: HTMLElement | null;
    currentStepIndex: number;
    previousStepIndex: number;
    steps: Step[];
    isScrollingIntoView: boolean; // Whether scrolling element into view or not
    focus: (scrollBehavior?: 'auto' | 'smooth') => void; // programmatically focus current targe, In case it loses
    goto: (stepIndex: number) => void; // goto any specific steps
    next: () => void;
    prev: () => void;
    onRequestClose: ((params: {event: MouseEvent | PointerEvent, isMask: boolean, isOverlay: boolean}) => void) | null
}

Passing Ref to TourNavigator

Since TourNavigator is a class component, you can use ref to access various built-in methods directly for enhanced customization.

This README provides an overview of the package, its usage, props, and default props. Let me know if you need further modifications or additions!

License

This project is licensed under the MIT.