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

`javascript
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
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, |

$3

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

`javascript
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
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, |

$3

`typescript
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;
}
`

$3

`typescript
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
}
``

$3

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!

$3

This project is licensed under the MIT.