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 →
ℹ️ 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
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.
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 |
The element to anchor the tour item to.
Name | Type | Description |
---|---|---|
children | ReactElement | A React element to anchor to |
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 |
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 |
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 |
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 |
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 |
The dismiss icon of the tour item popover. Extends HTMLButtonElement
.
Name | Type | Description |
---|---|---|
theme? | Theme | A theme definition to attach to the component |
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 |
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 |
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 |
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 |
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 |
If you are planning to only use the tour headlessly, you can import the hooks alone using @dopt/react-tour/hooks
.
-
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(
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>
);
}
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 |
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 |
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 |
Name | Selector | Description |
---|---|---|
active | .dopt-tour-item-progress__item--active |
Active progress item |
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;
}
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;
}
type FilterableField = 'completed' | 'not-completed' | 'active' | 'not-active';
type CountableField = FilterableField;
type Alignment = 'start' | 'center' | 'end';
type Side = 'top' | 'right' | 'bottom' | 'left';