<p align="center"> <a href="reactour.js.org"> <img alt="Reactour" title="Reactour" src="https://raw.githubusercontent.com/elrumordelaluz/reactour/main/logo.svg" width="250"></a> </p> <p align="center" style="margin-top: 40px;margin-bottom: 40px;"> <st
npm install @reactour/tour
Tourist Guide into your React Components
> This documentation is for the latest release, which uses npm scoped package @reactour. The original reactour is now on branch v1 and its documentation can be found here.
``zsh`
npm i -S @reactour/touror
yarn add @reactour/tour
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 is the perfect place to play aroud with all
@reactour _Components_. Here is an online version.#### Sandboxes
- Using React Router
- Using React Router with automatic route switching
- Using React Modal
- Using Semantic UI Modal
- Using React Bootstrap Modal
- Tour with data fetching

> Feel free to make a PR proposing new sandboxes or demos to add in the playground.
TourProvider$3
Array of elements to highlight with special info and props.
StepType
####
selector: string | ElementA string containing one CSS Selector to match and highlight the element at the time of this step.
####
content: string | ({ setCurrentStep, transition, isHighlightingObserved, currentStep, setIsOpen }) => voidThe 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 to be included (by union) in the highlighted region of the _Mask_.
####
mutationObservables?: string[]Array of CSS Selector that addition or removal will triggered a rerender of the _Mask_ shape.
####
resizeObservables?: string[]Array of CSS Selector that when resizeing each will triggered a rerender of the _Mask_ shape.
####
navDotAriaLabel?: stringString to assign to
aria-label attribute of the _Dot_ of this step.####
stepInteraction?: booleanAllow to reenable the interaction for this specific step, when
disableInteraction (from _TourProvider_) is true.####
action?: (elem: Element | null) => voidAction fired when the _Tour_ arrives in this step.
####
actionAfter?: (elem: Element | null) => voidAction fired when the _Tour_ leaves this step.
####
disableActions?: booleanAllow 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?: PaddingControl padding spaces for this specific step.
####
bypassElem?: booleanExcludes the main
selector when calculating highlited area if present highlightedSelectors.####
styles?: StylesObj & PopoverStylesObj & MaskStylesObjCustomize styles fro this specific step.
$3
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 (
styles={{ badge: (base) => ({ ...base, backgroundColor: 'red' }) }}
>
👉 {children} 👈
)
}
function Close({ onClick }) {
return (
onClick={onClick}
style={{ position: 'absolute', right: 0, top: 0 }}
>
x
)
}
const steps = [
/ ... /
]
export default function App() {
return (
{/ ... /}
)
}
`$3
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 and Popover docs 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' }),
}
`$3
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.$3
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$3
Function to control the _Tour_ current step state.
$3
Custom _Tour_ current
step state.stepInteraction prop.$3
Disables the ability to click or interact in any way with the Highlighted element on every step.
stepInteraction prop.$3
The _Tour_ uses FocusScope in order to lock the
focus iteration inside the _Popover_ when _Tour_ is active. This prop allows to disable this behaviour.$3
Disable interactivity with _Dot_ navigation inside _Popover_.
$3
If true, don't show tours when
selector or document.getElementById(step.selector) is falsy.$3
Type details
`ts
type KeyboardParts = 'esc' | 'left' | 'right'
`Disable all keyboard navigation events when
true, disable only selected keys when array.default:
false$3
Class assigned to _Popover_.
default:
reactour__popover$3
Class assigned to _Mask_.
default:
reactour__mask$3
Class assigned to highlighted part of _Mask_. Useful when using
disableInteraction.$3
$3
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.$3
Action fired just after the _Tour_ is open.
$3
Action fired just before the _Tour_ is closed.
$3
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.
$3
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.
$3
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
steps={steps}
disableInteraction
onClickHighlighted={(e, clickProps) => {
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
}
`$3
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
steps={steps}
disableInteraction
keyboardHandler={(e, clickProps) => {
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)
}
}}
>
{/ ... /}
`$3
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.
$3
Show or hide the _Navigation_ (_Prev_ and _Next_ buttons and _Dots_) inside _Popover_.
$3
Show or hide _Prev_ and _Next_ buttons inside _Popover_.
$3
Show or hide the _Close_ button inside _Popover_.
$3
Show or hide the _Badge_ inside _Popover_.
$3
Show or hide _dots_ navigation inside _Popover_.
$3
Activate
smooth scroll behavior when steps are outside viewport.default:
false$3
Tolerance in pixels to add when calculating if the step element is outside viewport to scroll into view.
$3
Type details
`ts
type A11yOptions = {
ariaLabelledBy: string
closeButtonAriaLabel: string
showNavigationScreenReaders: boolean
}
`Configure generic accessibility related attributes like aria-labelledby, aria-label for _Close_ button and if show or hide _Dot_ navigation in screen readers.
$3
Option to navigate and show _Navigation_ in right-to-left mode
$3
Mask ID to pass directly into the Mask component
$3
Clip ID to pass directly into the Mask component
$3
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
`ts
type PositionType = (
postionsProps: PositionProps,
prev: RectResult
) => 'top' | 'right' | 'bottom' | 'left' | 'center' | [number, number]
`$3
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}
onClick={() => {
if (isLastStep) {
props.setIsOpen(false)
} else {
props.setCurrentStep((s) => s + 1)
}
}}
>
{isLastStep ? 'x' : '>'}
)
}const steps = [
/ ... /
]
function App() {
return (
steps={steps}
ContentComponent={ContentComponent}
styles={{ popover: (base) => ({ ...base, padding: 0 }) }}
>
{/ ... /}
)
}
`$3
Element which wraps the Tour, useful in case is needed to port the Tour into a Portal. Defaults to
React.FragmentuseTourLater 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}
>
)
}
`$3
Is the _Tour_ open or close
$3
The current step. zero based
$3
The
Array of steps set currently$3
SetState function open or close _Tour_$3
SetState function to update the Array of steps.$3
Global meta information that could be useful in complex Tour/s situtations
$3
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.withTourIn 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)
``