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.