Tourist Guide into your React Components

## Documentation [https://docs.react.tours](https://docs.react.tours/tour/quickstart) > This documentation is for the latest release, which uses [npm scoped package](https://docs.npmjs.com/cli/v7/using-npm/scope) `@reactour`. The original `reactour` is now on branch `v1` and its documentation can be found [here](https://github.com/elrumordelaluz/reactour/tree/v1). ## Install ```zsh npm i -S @reactour/tour # or yarn add @reactour/tour ``` ## Usage Add the `TourProvider` at the root of your Application, passing the `steps` of the elements to highlight during the _Tour_. ```js // ... import { TourProvider } from '@reactour/tour' ReactDOM.render( , document.getElementById('root') ) const steps = [ { selector: '.first-step', content: 'This is my first Step', }, // ... ] ``` Then somewhere down the Application tree, control the Tour using `useTour` hook. ```js import { useTour } from '@reactour/tour' function App() { const { setIsOpen } = useTour() return ( <>

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent at finibus nulla, quis varius justo. Vestibulum lorem lorem, viverra porta metus nec, porta luctus orci

) } ``` ## Examples #### Playground The [Playground](https://github.com/elrumordelaluz/reactour/tree/main/packages/playground) is the perfect place to play aroud with all `@reactour` _Components_. [Here](https://reactour.vercel.app) is an online version. #### Sandboxes - [Using React Router](https://codesandbox.io/s/reactour-tour-demo-using-react-router-dom-kujql) - [Using React Router with automatic route switching](https://codesandbox.io/s/tour-demo-using-react-router-dom-with-automatic-route-switching-fhdnxb?file=/src/App.js) - [Using React Modal](https://codesandbox.io/s/reactour-tour-demo-using-react-modal-8v0eo) - [Using Semantic UI Modal](https://codesandbox.io/s/reactour-tour-demo-using-semantic-ui-modal-xmqee) - [Using React Bootstrap Modal](https://codesandbox.io/s/reactour-tour-demo-using-react-bootstrap-modal-qjws4) - [Tour with data fetching](https://codesandbox.io/s/tour-with-data-fetching-dv2q0?file=/src/index.js) [![Edit @reactour/tour Demo Template](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/reactour-tour-demo-template-fglzv?fontsize=14&hidenavigation=1&theme=dark) > Feel free to make a PR proposing new sandboxes or demos to add in the playground. ## `TourProvider` ### `steps?: StepType[]` Array of elements to highlight with special info and props.

StepType

#### `selector: string | Element` A string containing one [CSS Selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) to match and highlight the element at the time of this step. #### `content: string | ({ setCurrentStep, transition, isHighlightingObserved, currentStep, setIsOpen }) => void` The content to show inside the _Popover_ at the time of this step. Using a `function` have parameters to use inside content. #### `position?: 'top' | 'right' | 'bottom' | 'left' | 'center' | [number, number]` The preferred postion to position the _Popover_ in relation with the highlighted element. Will be automatically calculated in case of unavailable space. #### `highlightedSelectors?: string[]` Array of [CSS Selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) to be included (by union) in the highlighted region of the _Mask_. #### `mutationObservables?: string[]` Array of [CSS Selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) that addition or removal will triggered a rerender of the _Mask_ shape. #### `resizeObservables?: string[]` Array of [CSS Selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) that when resizeing each will triggered a rerender of the _Mask_ shape. #### `navDotAriaLabel?: string` String to assign to `aria-label` attribute of the _Dot_ of this step. #### `stepInteraction?: boolean` Allow to reenable the interaction for this specific step, when `disableInteraction` (from _TourProvider_) is `true`. #### `action?: (elem: Element | null) => void` Action fired when the _Tour_ arrives in this step. #### `actionAfter?: (elem: Element | null) => void` Action fired when the _Tour_ leaves this step. #### `disableActions?: boolean` Allow to disable all possible actions (interaction with _Mask_, _Navigation Arrows_, _Navigation Dots_, _Close_ button and keyboard events) when the _Tour_ is in this step. #### `padding?: Padding` Control padding spaces for this specific step. #### `bypassElem?: boolean` Excludes the main `selector` when calculating highlited area if present `highlightedSelectors`. #### `styles?: StylesObj & PopoverStylesObj & MaskStylesObj` Customize styles fro this specific step.

### `components?: PopoverComponentsType` Prop to customize granurally each Component inside the _Popover_. #### Components available | key | props | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Badge` | `styles` | | `Close` | `styles`, `onClick`, `disabled` | | `Content` | `content`,`setCurrentStep`,`transition`, `isHighlightingObserved`,`currentStep`,`setIsOpen` | | `Navigation` | `styles`,`setCurrentStep`, `steps`, `currentStep`, `disableDots`, `nextButton`, `prevButton`, `setIsOpen`, `hideButtons`, `hideDots`, `disableAll`, `rtl`, `Arrow`, | | `Arrow` | `styles`, `inverted`, `disabled` |

Example

```js import { components } from '@reactour/tour' function Badge({ children }) { return ( ({ ...base, backgroundColor: 'red' }) }} > 👉 {children} 👈 ) } function Close({ onClick }) { return ( ) } const steps = [ /* ... */ ] export default function App() { return ( {/* ... */} ) } ```

### `styles?: 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. #### Style keys and props available Refer to [Mask docs](https://github.com/elrumordelaluz/reactour/tree/main/packages/mask) and [Popover docs](https://github.com/elrumordelaluz/reactour/tree/main/packages/popover) for its specific Components ##### Tour Components | key | props | | ---------- | ----------------------------------- | | `badge` | | | `controls` | | | `button` | `disabled` | | `arrow` | `disabled` | | `dot` | `current`, `disabled`, `showNumber` | | `close` | `disabled` |

Example

```js const styles = { maskWrapper: (base) => ({ ...base, color: 'red', }), highlightedArea: (base, { x, y }) => ({ ...base, x: x + 10, y: y + 10, }), badge: (base) => ({ ...base, color: 'blue' }), } ```

### `padding?: Padding`

Type details

```ts type Padding = | number | { mask?: ComponentPadding popover?: ComponentPadding wrapper?: ComponentPadding } // x and y same value or [x, y] or [top, x, bottom] or [top, right, bottom, left] type ComponentPadding = number | number[] ```

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?: Position`

Type details

```ts type Position = | 'top' | 'right' | 'bottom' | 'left' | 'center' | [number, number] | ((postionsProps: PositionProps) => Position) type PositionProps = { bottom: number height: number left: number right: number top: number width: number windowWidth: number windowHeight: number } ```

Set a global position for the _Popover_ in all steps, fixed in case of `[number, number]`, calculated in case of position `string` ### `setCurrentStep: Dispatch>` Function to control the _Tour_ current step state. ### `currentStep: number` Custom _Tour_ current `step` state. This option could be overrided on specific steps using [`stepInteraction`](#stepinteraction-boolean) prop. ### `disableInteraction?: boolean | ((clickProps: Pick) => boolean)` Disables the ability to click or interact in any way with the Highlighted element on every step. This option could be overrided on specific steps using [`stepInteraction`](#stepinteraction-boolean) prop. ### `disableFocusLock?: boolean` The _Tour_ uses [FocusScope](https://react-spectrum.adobe.com/react-aria/FocusScope.html) in order to lock the `focus` iteration inside the _Popover_ when _Tour_ is active. This prop allows to disable this behaviour. ### `disableDotsNavigation?: boolean` Disable interactivity with _Dot_ navigation inside _Popover_. ### `disableWhenSelectorFalsy?: boolean` If true, don't show tours when `selector` or `document.getElementById(step.selector)` is falsy. ### `disableKeyboardNavigation?: boolean | KeyboardParts[]`

Type details

```ts type KeyboardParts = 'esc' | 'left' | 'right' ```

Disable all keyboard navigation events when `true`, disable only selected keys when array. default: `false` ### `className?: string` [Class](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/class) assigned to _Popover_. default: `reactour__popover` ### `maskClassName?: string` [Class](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/class) assigned to _Mask_. default: `reactour__mask` ### `highlightedMaskClassName?: string` [Class](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/class) assigned to highlighted part of _Mask_. Useful when using [`disableInteraction`](#disableinteraction-boolean). ### `nextButton?: (props: BtnFnProps) => void` ### `prevButton?: (props: BtnFnProps) => void`

Type details

```ts type BtnFnProps = { Button: React.FC setCurrentStep: Dispatch> stepsLength: number currentStep: number setIsOpen: Dispatch> } type NavButtonProps = { onClick?: () => void kind?: 'next' | 'prev' hideArrow?: boolean } ```

Helper functions to customize the _Next_ and _Prev_ buttons inside _Popover_, with useful parameters. It is possible to use the base `Button` and customize the props. ### `afterOpen?: (target: Element | null) => void` Action fired just after the _Tour_ is open. ### `beforeClose?: (target: Element | null) => void` Action fired just before the _Tour_ is closed. ### `onClickMask?: (clickProps: ClickProps) => void`

Type details

```ts type ClickProps = { setIsOpen: Dispatch> setCurrentStep: Dispatch> setSteps: Dispatch> setMeta: Dispatch> currentStep: number steps: StepType[] meta: string } ```

Function that overrides the default close behavior of the _Mask_ click handler. Comes with useful parameters to play with. ### `onClickClose?: (clickProps: ClickProps) => void`

Type details

```ts type ClickProps = { setIsOpen: Dispatch> setCurrentStep: Dispatch> setSteps: Dispatch> setMeta: Dispatch> currentStep: number steps: StepType[] meta: string } ```

Function that overrides the default close behavior of the _Close icon_ click handler. Comes with useful parameters to play with. ### `onClickHighlighted?: (e: MouseEventHandler, 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.

Example

```jsx { 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) ) } }} > {/* ... */} ```

Type details

```ts type ClickProps = { setIsOpen: Dispatch> setCurrentStep: Dispatch> setSteps: Dispatch> setMeta: Dispatch> currentStep: number steps: StepType[] meta: string } ```

### `keyboardHandler?: KeyboardHandler` Function to handle keyboard events in a custom way.

Type details

```ts type KeyboardHandler = { keyboardHandler?: ( e: KeyboardEvent, clickProps?: ClickProps, status?: { isEscDisabled?: boolean isRightDisabled?: boolean isLeftDisabled?: boolean } ) => void } ```

Example

```jsx { 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) } }} > {/* ... */} ```

### `badgeContent?: (badgeProps: BadgeProps) => any`

Type details

```ts type BadgeProps = { totalSteps: number currentStep: number transition: boolean } ```

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?: boolean` Show or hide the _Navigation_ (_Prev_ and _Next_ buttons and _Dots_) inside _Popover_. ### `showPrevNextButtons?: boolean` Show or hide _Prev_ and _Next_ buttons inside _Popover_. ### `showCloseButton?: boolean` Show or hide the _Close_ button inside _Popover_. ### `showBadge?: boolean` Show or hide the _Badge_ inside _Popover_. ### `showDots?: boolean` Show or hide _dots_ navigation inside _Popover_. ### `scrollSmooth?: boolean` Activate `smooth` scroll behavior when steps are outside viewport. default: `false` ### `inViewThreshold?: { x?: number, y?: number } | number` Tolerance in pixels to add when calculating if the step element is outside viewport to scroll into view. ### `accessibilityOptions?: A11yOptions`

Type details

```ts type A11yOptions = { ariaLabelledBy: string closeButtonAriaLabel: string showNavigationScreenReaders: boolean } ```

Configure generic accessibility related attributes like [aria-labelledby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-labelledby_attribute), [aria-label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-label_attribute) for _Close_ button and if show or hide _Dot_ navigation in screen readers. ### `rtl?: boolean` Option to navigate and show _Navigation_ in right-to-left mode ### `maskId?: string` Mask ID to pass directly into the [Mask component](https://github.com/elrumordelaluz/reactour/tree/main/packages/mask#maskid-string) ### `clipId?: string` Clip ID to pass directly into the [Mask component](https://github.com/elrumordelaluz/reactour/tree/main/packages/mask#clipid-string) ### `onTransition?: 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

Type details

### `ContentComponent?: ComponentType` Completelly custom component to render inside the _Popover_.

Type details

```ts type PopoverContentProps = { styles?: StylesObj & PopoverStylesObj & MaskStylesObj badgeContent?: (badgeProps: BadgeProps) => any components?: PopoverComponentsType accessibilityOptions?: A11yOptions disabledActions?: boolean onClickClose?: (clickProps: ClickProps) => void setCurrentStep: Dispatch> currentStep: number transition?: boolean isHighlightingObserved?: boolean setIsOpen: Dispatch> steps: StepType[] showNavigation?: boolean showPrevNextButtons?: boolean showCloseButton?: boolean showBadge?: boolean nextButton?: (props: BtnFnProps) => void prevButton?: (props: BtnFnProps) => void disableDotsNavigation?: boolean rtl?: boolean } ```

Example

```js function ContentComponent(props) { const isLastStep = props.currentStep === props.steps.length - 1 const content = props.steps[props.currentStep].content return (

{/* Check if the step.content is a function or a string */} {typeof content === 'function' ? content({ ...props, someOtherStuff: 'Custom Text' }) : content}

) } const steps = [ /* ... */ ] function App() { return ( ({ ...base, padding: 0 }) }} > {/* ... */} ) } ```

### `Wrapper?: ComponentType` Element which wraps the Tour, useful in case is needed to port the Tour into a [Portal](https://reactjs.org/docs/portals.html). Defaults to `React.Fragment` ## `useTour` Later in any Component down in the tree of _TourProvider_ you can control the _Tour_ in many ways ```jsx import { useTour } from '@reactour/tour' function MyComponent() { const { isOpen, currentStep, steps, setIsOpen, setCurrentStep, setSteps } = useTour() return ( <>

{isOpen ? 'Welcome to the tour!' : 'Thank you for participate!'}

Now you are visiting the place {currentStep + 1} of {steps.length}

) } ``` ### `isOpen: boolean` Is the _Tour_ open or close ### `currentStep: number` The current step. **zero based** ### `steps: StepType[]` The `Array` of steps set currently ### `setIsOpen: Dispatch>` `SetState` function open or close _Tour_ ### `setSteps: Dispatch>` `SetState` function to update the `Array` of steps. ### `meta: string` Global meta information that could be useful in complex Tour/s situtations ### `setMeta: Dispatch>` `SetState` function to update the global meta info. > **Warning**: Make sure you reset the `currentStep` value using the `setCurrentStep` function to ensure the tour will be opened to the correct step after update. Otherwise, in case where a person has already interacted with the tour steps and closed the tours on step 5 for example, they might open to the incorrect step, or similarly if the new set of steps only has 3 steps nothing will open. ## `withTour` In case you needed there is an enhancer that allows you to have all `useTour` functionalities through a Higher Order Component. ```jsx import { Component } from 'react' import { withTour } from '@reactour/tour' class MyComponent extends Component { render() { return ( <>

{/* ... */}

) } } export default withTour(MyCompnent) ```

Package	Téléchargements	Stars	Taille	Issues	Publication	Licence

@reactour/tour	79,625	3,976	98.4 kB	81	il y a un an	MIT