react-hook-tour

A product tour library using React Hooks

1.0.0-rc.3
Source
npm

Version published: 5 years ago

Weekly downloads: 2; decreased by-81.82%

Maintainers: 1

Weekly downloads

Created: 5 years ago

Source

React Hook Tour

A library for creating a product tour using React hooks

Getting Started

Install using a package manager:

npm install -S react-hook-tour

yard add --save react-hook-tour

Configure your tour and wrap your app with the TourProvider (see below for config options).

NOTE: A PopoverComponent is required, and it is recommended that you start with the template in example/PopoverTemplate.jsx:

import { TourProvider } from 'react-hook-tour'
import PopoverComponent from './Popover'

// configure the tour
const tourConfig = {
  name: 'My First Tour',
  PopoverComponent,
  stepOrder: [
    'welcome',
    'menu',
    {
      name: 'async',
      fetch: () => {
        router.push('/next-page-with-step')
      }
    },
    {
      name: 'preconfigured',
      hasBackdrop: true,
      title: 'Preconfigured Step',
      content: 'Steps can be fully configured up front'
    }
  ]
}
// somewhere at the top of your component tree:
return (
  <TourProvider config={tourConfig}>
    <MyApp>
  </TourProvider>
)

// in a nested component
import { useTour, useStep } from 'react-hook-tour'

export default props => {
  const tour = useTour()

  // configure your steps here and get a ref (see below for config options)
  const welcomeStep = useStep({
    name: 'welcome',
    isModal: true,
    hasBackdrop: true,
    title: 'Welcome!',
    content: 'Welcome to my site',
  })

  const menuStep = useStep({
    name: 'menu',
    hasBackdrop: true,
    title: 'Main Menu',
    content: 'Click here for more options',
  })

  // or reference a preconfigured step and get a ref
  const preconfiguredStep = useStep('preconfigured')

  return (
    <div ref={welcomeStep}>
      <div ref={menuStep}>Main Menu</div>
      <button ref={preconfiguredStep} onClick={tour.start}>Start Tour</div>
    </div>
  )
}

Config Options

stepOrder
name
placement
isModal
hasBackdrop
offset
scrollOffsets
PopoverComponent
popoverTemplate
popoverClassName
backdropClassName
onStart
onEnd
onNext
onPrev
onPause
onResume
onShow
onHide

`stepOrder <array>` required

Configurable for Tour only

All steps must be listed here. Each element in the array can either be a string representing the step name, a preconfigured step, or a step placeholder object.

If it's a string, the step must be registered by the time the previous step is displayed.

If it is an object, it can be a fully configured step and can contain any of the configuration options below, but it must not include a fetch() method.

Or, it can take the following options as a placeholder that instructs the tour to assume that the step exists but has not yet loaded:

name - required, the name of the step
fetch - required, a function the returns a promise. Called when the step is to be displayed but is not yet registered. It can change the route, fetch data, or conduct any other action that enabled the step to load and register. When present, the tour will pause and will only resume once the step is registered. Life cycle events can be used to manage the UI when in the fetching state.