@dopt/react-tour

Overview

A React tour component for building experiences with Dopt.

You can use the tour component out of the box as a pre-built component or break out and use it headlessly with your own UI component.

Learn more about how to use this component with Dopt →

Installation

ℹ️ If you are using a particular React framework like Next.js, please check out our framework specific docs.

# npm
npm install @dopt/react-tour

# Yarn
yarn add @dopt/react-tour

# pnpm
pnpm add @dopt/react-tour

Usage

The default export from @dopt/react-tour is a collection of components that you can use to structure and compose a tour item.

import TourItem, { useTourItem } from '@dopt/react-tour';

function MyTourStep({ children }) {
  const tourItem = useTourItem('tour.shaggy-horses-sniff');

  if (!tourItem) {
    return children;
  }

  return (
    <TourItem.Root active={tourItem.active}>
      <TourItem.Anchor>{children}</TourItem.Anchor>
      <TourItem.Popover>
        <TourItem.Content>
          <TourItem.Header>
            <TourItem.Title>{tourItem.title}</TourItem.Title>
            <TourItem.DismissIcon onClick={tourItem.tour?.dismiss} />
          </TourItem.Header>
          <TourItem.Body>{tourItem.body}</TourItem.Body>
          <TourItem.Footer>
            <TourItem.BackButton>{tourItem.backLabel}</TourItem.BackButton>
            <TourItem.NextButton onClick={tourItem.next}>
              {tourItem.nextLabel}
            </TourItem.NextButton>
          </TourItem.Footer>
          <TourItem.Progress
            count={tourItem.tour?.size || 1}
            index={tourItem.index}
          />
        </TourItem.Content>
      </TourItem.Popover>
    </TourItem.Root>
  );
}

Check out our tour example and our headless tour example for more in-depth usage.

Props

Root

The root element of the tour item.

Name	Type	Description
active?	boolean	Determines the visibility of the component (default: false)
children?	ReactNode	The contents of the component
theme?	Theme	A theme definition to attach to the component

Anchor

The element to anchor the tour item to.

Name	Type	Description
children	ReactElement	A React element to anchor to

Popover

The tour item popover. Extends HTMLDivElement.

Name	Type	Description
alignment?	Alignment	Determines how the component should align relative to the anchor element (default: center)
children?	ReactNode	The contents of the component
offset?	number	The distance in px to position the component relative to the anchor element (default: 10)
position?	Side	The side that the component should position relative to the anchor element (default: top)
theme?	Theme	A theme definition to attach to the component

Content

The content of the tour item popover. Extends HTMLDivElement.

Name	Type	Description
children?	ReactNode	The contents of the component
theme?	Theme	A theme definition to attach to the component

Header

The header of the tour item popover. Extends HTMLElement.

Name	Type	Description
children?	ReactNode	The contents of the component
theme?	Theme	A theme definition to attach to the component

Title

The title of the tour item popover. Extends HTMLHeadingElement.

Name	Type	Description
children?	ReactNode	The contents of the component
theme?	Theme	A theme definition to attach to the component

Content

The content of the tour item popover. Extends HTMLDivElement.

Name	Type	Description
children?	ReactNode	The contents of the component
theme?	Theme	A theme definition to attach to the component

DismissIcon

The dismiss icon of the tour item popover. Extends HTMLButtonElement.

Name	Type	Description
theme?	Theme	A theme definition to attach to the component

Body

The body of the tour item popover. Extends HTMLDivElement.

Name	Type	Description
children?	RichText	The rich text contents of the component
theme?	Theme	A theme definition to attach to the component

Footer

The footer of the tour item popover. Extends HTMLElement.

Name	Type	Description
children?	ReactNode	The contents of the component
theme?	Theme	A theme definition to attach to the component

NextButton

The next button of the tour item popover. Extends HTMLButtonElement.

Name	Type	Description
children?	ReactNode	The contents of the component
theme?	Theme	A theme definition to attach to the component

BackButton

The back button of the tour item popover. Extends HTMLButtonElement.

Name	Type	Description
children?	ReactNode	The contents of the component
theme?	Theme	A theme definition to attach to the component

Progress

The progress indicators of the tour item popover. Extends HTMLOListElement.

Name	Type	Description
count	number	The total count of items
index	number	The current item index
theme?	Theme	A theme definition to attach to the component

Hooks

If you are planning to only use the tour headlessly, you can import the hooks alone using @dopt/react-tour/hooks.

useTour

• useTour(id: string): Tour

A React hook for accessing and updating a Tour's state.

import { useTour } from '@dopt/react-tour';

export function MyTourStep() {
  const {
    id,
    items,
    active,
    completed,
    dismissed,
    complete,
    dismiss,
    filter,
    count,
    size,
  } = useTour('onboarding-tour.tour-component');

  return (
    <div>
      <div id="states">
        <div>tour.active: {active}</div>
        <div>tour.completed: {completed}</div>
        <div>tour.dismissed: {dismissed}</div>
      </div>
      <div id="actions">
        <button onClick={complete}>Complete</button>
        <button onClick={dismiss}>Dismiss</button>
      </div>
      <div id="children">
        <div>tour.items: {JSON.stringify(items.map((item) => item.id))}</div>
      </div>
      <div id="filtering">
        <div id="active-items">{JSON.stringify(filter('active'))}</div>
        <div id="not-active-items">{JSON.stringify(filter('not-active'))}</div>
        <div id="completed-items">{JSON.stringify(filter('completed'))}</div>
        <div id="not-completed-items">
          {JSON.stringify(filter('not-completed'))}
        </div>
      </div>
      <div id="metadata">
        <div>tour.size: {size}</div>
      </div>
    </div>
  );
}

useTourItem

• useTourItem(id): TourItem

A React hook for accessing and updating a tour item's state.

import { useTourItem } from '@dopt/react-tour';
import RichText from '@dopt/react-rich-text';

export function Application() {
  const {
    id,
    tour,
    index,
    title,
    body,
    nextLabel,
    backLabel,
    active,
    completed,
    next,
    back,
  } = useTourItem('onboarding-tour.step-1');

  return (
    <div>
      <div id="states">
        <div>tourItem.active: {active}</div>
        <div>tourItem.completed: {completed}</div>
      </div>
      <div id="actions">
        <button onClick={next}>{nextLabel}</button>
        <button onClick={back}>{backLabel}</button>
      </div>
      <div id="content">
        <div>tourItem.title: {title}</div>
        <div>
          tourItem.body: <RichText>{body}</RichText>
        </div>
        <div>tourItem.nextLabel: {nextLabel}</div>
        <div>tourItem.backLabel: {backLabel}</div>
      </div>
      <div id="parent">
        <div>tourItem.tour: {JSON.stringify(tour)}</div>
      </div>
      <div id="metadata">
        <div>tourItem.index: {tourItem.index}</div>
      </div>
    </div>
  );
}

Styling API

Learn more about styling and theming →

Name	Selector	Description
popover	.dopt-tour-item	Popover element
content	.dopt-tour-item__content	Content container
header	.dopt-tour-item__header	Header containing title and dismiss icon
title	.dopt-tour-item__title	Title heading
dismissIcon	.dopt-tour-item__dismiss-icon	Disiss icon button
body	.dopt-tour-item__body	Body content
footer	.dopt-tour-item__footer	Footer containing back and next buttons
backButton	.dopt-tour-item__back-button	Back button
nextButton	.dopt-tour-item__next-button	Next button
progress	.dopt-tour-item__progress	Progress indicators
progressItem	.dopt-tour-item-progress__item	Progress indicator item

Popover position

Name	Selector	Description
top	.dopt-tour-item--top	Positioned top
top	[data-position="top"]	Positioned top
right	.dopt-tour-item--right	Positioned right
right	[data-position="right"]	Positioned right
bottom	.dopt-tour-item--bottom	Positioned bottom
bottom	[data-position="bottom"]	Positioned bottom
left	.dopt-tour-item--left	Positioned left
left	[data-position="left"]	Positioned left

Popover alignment

Name	Selector	Description
start	.dopt-tour-item--start	Aligned start
start	[data-alignment="start"]	Aligned start
center	.dopt-tour-item--center	Aligned center
center	[data-alignment="center"]	Aligned center
end	.dopt-tour-item--end	Aligned end
end	[data-alignment="end"]	Aligned end

Progress item state

Name	Selector	Description
active	.dopt-tour-item-progress__item--active	Active progress item

Types

Tour

A stateful container for tour items.

interface Tour {
  id: string;

  items: TourItem[];

  active: boolean;

  completed: boolean;
  dismissed: boolean;

  complete: () => void;
  dismiss: () => void;

  size: number;

  filter(on: FilterableField): TourItem[];
  count(where: CountableField): number;
}

TourItem

A child of the tour. Includes state accessors and methods for updating state along with content configured in Dopt.

interface TourItem {
  id: string;

  tour: Tour | undefined;

  index: number | null | undefined;

  title: string | null | undefined;
  body: RichText | null | undefined;

  nextLabel: string | null | undefined;
  backLabel: string | null | undefined;

  active: boolean;

  completed: boolean;

  next: () => void;
  back: () => void;
}

FilterableField

type FilterableField = 'completed' | 'not-completed' | 'active' | 'not-active';

CountableField

type CountableField = FilterableField;

Alignment

type Alignment = 'start' | 'center' | 'end';

Position

type Side = 'top' | 'right' | 'bottom' | 'left';