├── README.md
├── _snippets
└── snippet-example.mdx
├── examples.mdx
├── favicon.png
├── images
├── reactour-hero-dark.svg
└── reactour-hero-light.svg
├── introduction.mdx
├── logo
├── reactour-logo-dark.svg
└── reactour-logo-light.svg
├── mask
├── props.mdx
└── quickstart.mdx
├── mint.json
├── popover
├── props.mdx
└── quickstart.mdx
├── quickstart.mdx
└── tour
├── hooks.mdx
├── props.mdx
└── quickstart.mdx
/README.md:
--------------------------------------------------------------------------------
1 | # Reactour docs
2 |
3 | It uses [Mintlify](https://mintlify.com/)
4 |
5 | ### Development
6 |
7 | Install the [Mintlify CLI](https://www.npmjs.com/package/mintlify) to preview the documentation changes locally. To install, use the following command
8 |
9 | ```
10 | npm i -g mintlify
11 | ```
12 |
13 | Run the following command at the root of your documentation (where mint.json is)
14 |
15 | ```
16 | mintlify dev
17 | ```
18 |
--------------------------------------------------------------------------------
/_snippets/snippet-example.mdx:
--------------------------------------------------------------------------------
1 | ## My Snippet
2 |
3 | This is an example of a reusable snippet
4 |
--------------------------------------------------------------------------------
/examples.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Examples"
3 | description: "A starting point to test features"
4 | icon: "circle-play"
5 | ---
6 |
7 | ## Demo
8 |
9 | Make a quick tour with the basic features on the main demo:
10 |
11 |
12 |
13 | The Tourist Guide which puts together the Mask, the Popover and more magic!
14 |
15 |
16 |
17 | ## Sandboxes
18 |
19 | Easily editable sandboxes to play and fork, just to test stuff or to include when opening issues or PR:
20 |
21 | [](https://codesandbox.io/s/reactour-tour-demo-template-fglzv?fontsize=14&hidenavigation=1&theme=dark)
22 |
23 |
24 |
29 | Shows how to maintain Tour when changing pages
30 |
31 |
36 | Same as the other but with automatic route switching
37 |
38 |
43 | Shows Tour behavior when interacting with Modals
44 |
45 |
50 | Shows Tour behavior when interacting with Modals
51 |
52 |
57 | Shows Tour behavior when interacting with Modals
58 |
59 |
64 | Shows behavior while waiting for api responses
65 |
66 |
67 |
--------------------------------------------------------------------------------
/favicon.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/elrumordelaluz/docs/24c9d99a268dc82adea50db1a9b7661e6065542f/favicon.png
--------------------------------------------------------------------------------
/images/reactour-hero-dark.svg:
--------------------------------------------------------------------------------
1 |
2 |
3 |
133 |
--------------------------------------------------------------------------------
/images/reactour-hero-light.svg:
--------------------------------------------------------------------------------
1 |
2 |
3 |
135 |
--------------------------------------------------------------------------------
/introduction.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Welcome
3 | description: "a Tourist Guide into your React Components"
4 | icon: "handshake"
5 | ---
6 |
7 |
12 |
17 |
18 | ## Introduction
19 |
20 | Before onboarding products became widespread, I found myself with the need to create a "tour" for new users of different projects, with a nice look and above all with the possibility to interact with existing elements of the page. Thus was born this project in 2017, trying to simplify the logic of [intro.js](https://introjs.com/) with React components, prioritising to use svg and css features.
21 |
22 | With the passage of time and especially with the valuable feedback from users, the package was divided into three main packages that can be used independently: the mask, the popover and the tour (which brings everything together). In addition, the repository has become a single-purpose repository rewritten in typescript.
23 |
24 | Let's start the Tour together!
25 |
26 | ## Packages
27 |
28 |
29 |
30 | An SVG intelligent mask that cover all the contents except the part
31 | specified
32 |
33 |
34 | A popover positioned based on certain values
35 |
36 |
37 |
38 |
39 | The Tourist Guide which puts together the Mask, the Popover and more magic!
40 |
41 |
42 |
--------------------------------------------------------------------------------
/logo/reactour-logo-dark.svg:
--------------------------------------------------------------------------------
1 |
2 |
3 |
50 |
--------------------------------------------------------------------------------
/logo/reactour-logo-light.svg:
--------------------------------------------------------------------------------
1 |
2 |
3 |
50 |
--------------------------------------------------------------------------------
/mask/props.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Mask props"
3 | description: "Properties to customize Mask"
4 | icon: "mask"
5 | ---
6 |
7 |
8 | Object containing size and position informations of where to position the Mask
9 |
10 | Based on [getBoundingClientRect](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect) structure
11 |
12 | Width of the `rect`
13 |
14 |
15 | Height of the `rect`
16 |
17 |
18 | Top of the `rect`
19 |
20 |
21 | Left of the `rect`
22 |
23 |
24 | Bottom of the `rect`
25 |
26 |
27 | Right of the `rect`
28 |
29 |
30 |
31 |
32 |
33 |
34 | [CSS
35 | classname](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/class)
36 | to apply to the _Mask_ wrapper
37 |
38 |
39 |
40 | [CSS
41 | classname](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/class)
42 | to apply to the _Highlighted_ area `rect` element
43 |
44 |
45 |
46 | Extra space to add in _Mask_ calculations. Useful when calculating space from
47 | _Element_ bounding rect and want to add more space.
48 |
49 |
50 | Calculation is based on [padding shorthand syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/padding#syntax)
51 |
52 | Apply to all four sides
53 |
54 | Example: `100`
55 |
56 |
57 | top and bottom | left and right
58 |
59 | Example: `[10, 20]`
60 |
61 |
62 | top | left and right | bottom
63 |
64 | Example: `[10, 20, 5]`
65 |
66 |
67 | top | right | bottom | left
68 |
69 | Example: `[10, 20, 5, 10]`
70 |
71 |
72 |
73 |
74 |
75 |
76 |
77 | Extra space to add between viewport with and height.
78 |
79 |
80 | Calculation is based on [padding shorthand syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/padding#syntax)
81 |
82 | Apply to all four sides
83 |
84 | Example: `100`
85 |
86 |
87 | top and bottom | left and right
88 |
89 | Example: `[10, 20]`
90 |
91 |
92 | top | left and right | bottom
93 |
94 | Example: `[10, 20, 5]`
95 |
96 |
97 | top | right | bottom | left
98 |
99 | Example: `[10, 20, 5, 10]`
100 |
101 |
102 |
103 |
104 |
105 |
106 |
107 | Click handler for the _Mask_ except the highlighted area.
108 |
109 |
110 |
114 | Click handler for the _Highlighted_ area.
115 |
116 |
117 |
118 | String to be assigned to the `` element, otherwise an automatic unique
119 | id is assigned.
120 |
121 |
122 |
123 | String to be assigned to the `` element, otherwise an automatic
124 | unique id is assigned.
125 |
126 |
127 |
128 | Prop to customize styles for the different parts of the _Mask_ using a
129 | function that allows to extend the base styles an take advantage of some state
130 | props.
131 |
132 |
133 |
134 | Styles keys and its props available to customize
135 |
136 |
137 |
138 |
139 |
140 |
141 |
142 |
143 |
144 |
145 |
146 | ```js
147 | const styles = {
148 | maskWrapper: (base) => ({
149 | ...base,
150 | color: "red",
151 | }),
152 | highlightedArea: (base, { x, y }) => ({
153 | ...base,
154 | x: x + 10,
155 | y: y + 10,
156 | }),
157 | };
158 |
159 | function App() {
160 | return ;
161 | }
162 | ```
163 |
164 |
165 |
166 |
--------------------------------------------------------------------------------
/mask/quickstart.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Installation & Usage"
3 | description: "An SVG mask that cover all the window contents except the one specified by certain position and sizes values"
4 | icon: "mask"
5 | ---
6 |
7 | ### Install [@reactour/mask](https://www.npmjs.com/package/@reactour/mask)
8 |
9 |
10 |
11 | ```bash npm
12 | npm i -S @reactour/mask
13 | ```
14 |
15 | ```bash yarn
16 | yarn add @reactour/mask
17 | ```
18 |
19 |
20 |
21 | ### Usage
22 |
23 | ```js
24 | import { Mask } from "@reactour/mask";
25 |
26 | function App() {
27 | const sizes = {
28 | width: 100,
29 | height: 100,
30 | top: 100,
31 | left: 100,
32 | };
33 |
34 | return (
35 | <>
36 | {/* ... */}
37 |
38 |
39 | );
40 | }
41 | ```
42 |
--------------------------------------------------------------------------------
/mint.json:
--------------------------------------------------------------------------------
1 | {
2 | "$schema": "https://mintlify.com/schema.json",
3 | "name": "Reactour",
4 | "logo": {
5 | "dark": "/logo/reactour-logo-dark.svg",
6 | "light": "/logo/reactour-logo-light.svg"
7 | },
8 | "favicon": "/favicon.png",
9 | "colors": {
10 | "primary": "#2c697c",
11 | "light": "#43c6ac",
12 | "dark": "#0D001D",
13 | "background": {
14 | "dark": "#090014"
15 | },
16 | "anchors": {
17 | "from": "#2c697c",
18 | "to": "#43c6ac"
19 | }
20 | },
21 | "topbarLinks": [
22 | {
23 | "name": "Github",
24 | "url": "https://github.com/elrumordelaluz/reactour"
25 | }
26 | ],
27 | "topbarCtaButton": {
28 | "name": "Demo",
29 | "url": "https://www.react.tours/"
30 | },
31 |
32 | "anchors": [
33 | {
34 | "name": "Demo",
35 | "icon": "magnifying-glass",
36 | "url": "https://www.react.tours/"
37 | },
38 | {
39 | "name": "Website",
40 | "icon": "browser",
41 | "url": "https://elrumordelaluz.com"
42 | }
43 | ],
44 | "topAnchor": {
45 | "name": "Documentation",
46 | "icon": "book-open-cover"
47 | },
48 | "navigation": [
49 | {
50 | "group": "Get Started",
51 | "pages": ["introduction", "quickstart", "examples"]
52 | },
53 | {
54 | "group": "Mask",
55 | "pages": ["mask/quickstart", "mask/props"]
56 | },
57 | {
58 | "group": "Popover",
59 | "pages": ["popover/quickstart", "popover/props"]
60 | },
61 | {
62 | "group": "Tour",
63 | "pages": ["tour/quickstart", "tour/props", "tour/hooks"]
64 | }
65 | ],
66 | "footerSocials": {
67 | "twitter": "https://twitter.com/elrumordelaluz",
68 | "github": "https://github.com/elrumordelaluz",
69 | "instagram": "https://www.instagram.com/elrumordelaluz"
70 | },
71 | "feedback": {
72 | "thumbsRating": true,
73 | "suggestEdit": true,
74 | "raiseIssue": true
75 | }
76 | }
77 |
--------------------------------------------------------------------------------
/popover/props.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Popover props"
3 | description: "Properties to customize Popover"
4 | icon: "window-restore"
5 | ---
6 |
7 |
8 | Object containing size and position informations of where to position the Popover
9 |
10 | Based on [getBoundingClientRect](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect) structure
11 |
12 | Width of the `rect`
13 |
14 |
15 | Height of the `rect`
16 |
17 |
18 | Top of the `rect`
19 |
20 |
21 | Left of the `rect`
22 |
23 |
24 | Bottom of the `rect`
25 |
26 |
27 | Right of the `rect`
28 |
29 |
30 |
31 |
32 |
33 |
34 | The position for the Popover.
35 |
36 |
37 |
38 |
39 | Fixed in case of `[number, number]`, calculated prefered position in case of string.
40 |
41 |
42 |
43 |
44 |
45 |
46 |
47 |
48 |
49 |
50 |
51 |
52 |
53 |
54 |
55 |
56 |
57 | Extra space to add in _Mask_ calculations. Useful when calculating space from
58 | _Element_ bounding rect and want to add more space.
59 |
60 |
61 | Calculation is based on [padding shorthand syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/padding#syntax)
62 |
63 | Apply to all four sides
64 |
65 | Example: `100`
66 |
67 |
68 | top and bottom | left and right
69 |
70 | Example: `[10, 20]`
71 |
72 |
73 | top | left and right | bottom
74 |
75 | Example: `[10, 20, 5]`
76 |
77 |
78 | top | right | bottom | left
79 |
80 | Example: `[10, 20, 5, 10]`
81 |
82 |
83 |
84 |
85 |
86 |
87 |
88 | Prop to customize styles for the different parts of the _Popover_ using a
89 | function that allows to extend the base styles an take advantage of some state
90 | props.
91 |
92 |
93 |
94 | Styles keys and its props available to customize
95 |
96 |
97 |
98 |
99 |
100 |
101 |
102 | ```js
103 | const styles = {
104 | popover: (base) => ({
105 | ...base,
106 | boxShadow: "0 0 3em rgba(0, 0, 0, 0.5)",
107 | backgroundColor: "#dedede",
108 | }),
109 | };
110 |
111 | function App() {
112 | return ;
113 | }
114 | ```
115 |
116 |
117 |
118 |
119 |
120 | [CSS
121 | classname](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/class)
122 | to apply to the _Popover_
123 |
124 |
125 |
126 | Any value that if changed, updates rect calculations
127 |
128 |
--------------------------------------------------------------------------------
/popover/quickstart.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Installation & Usage"
3 | description: "A popover positioned based on certain values"
4 | icon: "window-restore"
5 | ---
6 |
7 | ### Install [@reactour/popover](https://www.npmjs.com/package/@reactour/popover)
8 |
9 |
10 |
11 | ```bash npm
12 | npm i -S @reactour/popover
13 | ```
14 |
15 | ```bash yarn
16 | yarn add @reactour/popover
17 | ```
18 |
19 |
20 |
21 | ### Usage
22 |
23 | ```js
24 | import { Popover } from '@reactour/popover'
25 |
26 | function App() {
27 | const sizes = {
28 | bottom: 0,
29 | left: 0,
30 | }
31 |
32 | return (
33 | <>
34 | {/* ... */}
35 |
36 |
37 | )
38 | }
39 | ```
40 |
--------------------------------------------------------------------------------
/quickstart.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Quickstart"
3 | description: "Add the Tour into your App easily"
4 | icon: "truck-fast"
5 | ---
6 |
7 | ### Install [@reactour/tour](https://www.npmjs.com/package/@reactour/tour)
8 |
9 |
10 |
11 | ```bash npm
12 | npm i -S @reactour/tour
13 | ```
14 |
15 | ```bash yarn
16 | yarn add @reactour/tour
17 | ```
18 |
19 |
20 |
21 | ### Usage
22 |
23 | 1. Add the `TourProvider` at the root of your Application, passing the steps of the elements to highlight during the Tour.
24 |
25 | ```js
26 | import { TourProvider } from "@reactour/tour";
27 |
28 | ReactDOM.render(
29 |
30 |
31 | ,
32 | document.getElementById("root")
33 | );
34 |
35 | const steps = [
36 | {
37 | selector: ".first-step",
38 | content: "This is my first Step",
39 | },
40 | // ...
41 | ];
42 | ```
43 |
44 | 2. Then somewhere down the Application tree, control the Tour using `useTour` hook.
45 |
46 | ```js
47 | import { useTour } from "@reactour/tour";
48 |
49 | function App() {
50 | const { setIsOpen } = useTour();
51 | return (
52 | <>
53 |
54 | Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent at
55 | finibus nulla, quis varius justo. Vestibulum lorem lorem, viverra porta
56 | metus nec, porta luctus orci
57 |
58 |
59 |
60 | );
61 | }
62 | ```
63 |
64 |
65 | Read the full Tour props
66 |
67 |
--------------------------------------------------------------------------------
/tour/hooks.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Tour hooks & HOC"
3 | description: "Hooks to interact with Tour"
4 | icon: "bus-simple"
5 | ---
6 |
7 | ## `useTour`
8 |
9 | Later in any Component down in the tree of _TourProvider_ you can control the _Tour_ in many ways
10 |
11 | ### Example
12 |
13 | ```js
14 | import { useTour } from '@reactour/tour'
15 |
16 | function MyComponent() {
17 | const { isOpen, currentStep, steps, setIsOpen, setCurrentStep, setSteps } = useTour()
18 | return (
19 | <>
20 |
{isOpen ? 'Welcome to the tour!' : 'Thank you for participate!'}
21 |
22 | Now you are visiting the place {currentStep + 1} of {steps.length}
23 |
24 |
41 |
42 | )
43 | }
44 | ```
45 |
46 | ### Values
47 |
48 |
49 | Is the Tour open or close
50 |
51 |
52 |
53 | The current step (zero based)
54 |
55 |
56 |
57 | The `array` of steps currently set
58 |
59 |
60 |
61 | [useState](https://react.dev/reference/react/useState) function to open or
62 | close Tour
63 |
64 |
65 |
69 | [useState](https://react.dev/reference/react/useState) function to update the
70 | `array` of steps
71 |
72 |
73 |
74 | Global meta information that could be useful in complex Tour/s situtations
75 |
76 |
77 |
78 | [useState](https://react.dev/reference/react/useState) function to update the
79 | global meta info
80 |
81 |
82 | ## `withTour`
83 |
84 | An enhancer that allows to have all `useTour` functionalities through a _Higher Order Component_.
85 |
86 | ```js
87 | import { Component } from "react";
88 | import { withTour } from "@reactour/tour";
89 |
90 | class MyComponent extends Component {
91 | render() {
92 | return (
93 | <>
94 |
95 |
{/* ... */}
96 |
97 | );
98 | }
99 | }
100 |
101 | export default withTour(MyCompnent);
102 | ```
103 |
--------------------------------------------------------------------------------
/tour/props.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Tour props"
3 | description: "Properties to customize the Tour"
4 | icon: "bus-simple"
5 | ---
6 |
7 |
8 | Array of elements to highlight with special info and props.
9 |
10 |
11 | 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.
12 |
13 |
14 | The content to show inside the [Popover](/popover) at the time of this step. Using a function, there are parameters with values, available to use as content.
15 |
16 |
17 | The preferred postion to position the [Popover](/popover) in relation with the highlighted element. Will be automatically calculated in case of unavailable space.
18 |
19 |
20 | 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](/mask).
21 |
22 |
23 | 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](/mask) shape.
24 |
25 |
26 | String to assign to `aria-label` attribute of the Dot button relative of this step in the navigation.
27 |
28 |
29 | Allow to reenable the interaction for this specific step, when `disableInteraction` (from `TourProvider`) is `true`.
30 |
31 |
32 | Action fired when as soon as _Tour_ arrives in this step.
33 |
34 |
35 | Action fired when as soon as _Tour_ leaves this step.
36 |
37 |
38 | Disable all possible actions when the Tour is in this step.
39 |
40 | Possible actions:
41 | - interaction with [Mask](/mask)
42 | - Navigation Arrows
43 | - Navigation Dots
44 | - Close button
45 | - keyboard events
46 |
47 | Control padding spaces for this specific step.
48 |
49 | Excludes the main `selector` when calculating highlited area if present `highlightedSelectors`.
50 |
51 |
52 |
53 | Customize styles fro this specific step.
54 |
55 |
56 |
57 |
58 |
59 |
60 | Customize granurally each Component inside the [Popover](/popover).
61 |
62 | Available Components and its `props`
63 |
64 |
65 |
69 |
73 |
74 |
75 |
76 |
77 |
78 | ```js
79 | import { components } from "@reactour/tour";
80 |
81 | function Badge({ children }) {
82 | return (
83 | ({ ...base, backgroundColor: "red" }) }}
85 | >
86 | 👉 {children} 👈
87 |
88 | );
89 | }
90 |
91 | function Close({ onClick }) {
92 | return (
93 |
99 | );
100 | }
101 |
102 | const steps = [
103 | /* ... */
104 | ];
105 |
106 | export default function App() {
107 | return (
108 |
109 | {/* ... */}
110 |
111 | );
112 | }
113 | ```
114 |
115 |
116 |
117 |
118 |
122 | Prop to customize styles for the different parts of the Mask, Popover and Tour
123 | using a function that allows to extend the base styles an take advantage of
124 | some state props.
125 |
126 |
127 | Styles keys and its props available to customize. Refer to [Mask
128 | docs](/mask/props) and [Popover docs](/popover/props) for its specific styles
129 | keys
130 |
131 |
132 |
133 |
134 |
135 |
136 |
137 |
138 |
139 |
140 | ```js
141 | const styles = {
142 | maskWrapper: (base) => ({
143 | ...base,
144 | color: "red",
145 | }),
146 | highlightedArea: (base, { x, y }) => ({
147 | ...base,
148 | x: x + 10,
149 | y: y + 10,
150 | }),
151 | badge: (base) => ({ ...base, color: "blue" }),
152 | };
153 |
154 | function App() {
155 | return ;
156 | }
157 | ```
158 |
159 |
160 |
161 |
162 |
163 | 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.
164 |
165 |
166 |
167 |
168 |
169 |
170 | Calculation is based on [padding shorthand syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/padding#syntax)
171 |
172 |
173 | Apply to all four sides
174 |
175 | Example: `100`
176 |
177 |
178 | top and bottom | left and right
179 |
180 | Example: `[10, 20]`
181 |
182 |
183 | top | left and right | bottom
184 |
185 | Example: `[10, 20, 5]`
186 |
187 |
188 | top | right | bottom | left
189 |
190 | Example: `[10, 20, 5, 10]`
191 |
192 |
193 |
194 |
195 |
196 |
197 |
198 |
199 | Set the global position value for the [Popover](/popover) in all steps
200 |
201 |
202 |
203 |
204 | Fixed in case of `[number, number]`, calculated prefered position in case of `string`.
205 |
206 |
207 |
208 |
209 |
210 |
211 |
212 |
213 |
214 |
215 |
216 |
217 |
218 |
219 |
220 |
221 |
225 | Function to control the Tour current step state.
226 |
227 |
228 |
232 | Custom Tour current step state.
233 |
234 |
235 |
236 |
240 | Disables the ability to click or interact in any way with the Highlighted element on every step.
241 |
242 | This option could be overrided on specific steps using `stepInteraction` prop.
243 |
244 |
245 |
246 |
247 | The Tour uses
248 | [FocusScope](https://react-spectrum.adobe.com/react-aria/FocusScope.html) in
249 | order to lock the focus iteration inside the [Popover](/popover) when _Tour_
250 | is active. This prop disables this behaviour.
251 |
252 |
253 |
254 | Disable interactivity with Dot navigation inside [Popover](/popover).
255 |
256 |
257 |
258 | If true, don't show tours when selector or
259 | `document.getElementById(step.selector)` is falsy.
260 |
261 |
262 |
267 | Disable all keyboard navigation events when true, disable only selected keys
268 | when array.
269 |
270 |
271 |
272 |
273 |
274 |
275 |
276 | [CSS
277 | classname](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/class)
278 | assigned to the [Popover](/popover)
279 |
280 |
281 |
282 | [CSS
283 | classname](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/class)
284 | assigned to the [Mask](/mask)
285 |
286 |
287 |
292 | [CSS
293 | classname](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/class)
294 | assigned to _highlighted_ part of the [Mask](/mask). Useful when using
295 | `disableInteraction`.
296 |
297 |
298 |
299 | Helper functions to customize the Next button inside [Popover](/popover), with
300 | useful parameters. It is possible to use the base _Button_ and customize the
301 | props.
302 |
303 |
304 |
305 |
306 |
307 |
308 |
309 |
310 |
311 |
312 |
313 |
314 |
315 |
316 |
317 |
318 |
319 |
320 | Helper functions to customize the Prev button inside [Popover](/popover), with
321 | useful parameters. It is possible to use the base _Button_ and customize the
322 | props.
323 |
324 |
325 |
326 |
327 |
328 |
329 |
330 |
331 |
332 |
333 |
334 |
335 |
336 |
337 |
338 |
339 |
340 |
341 | Action fired just after the Tour is open.
342 |
343 |
344 |
345 | Action fired just before the Tour is closed.
346 |
347 |
348 |
349 | Function that overrides the default close behavior of the [Mask](/mask) click
350 | handler. Comes with useful parameters to play with.
351 |
352 |
353 |
357 |
361 |
365 |
366 |
367 |
368 |
369 |
370 |
371 |
372 |
373 | Function that overrides the default close behavior of the Close icon click handler. Comes with useful parameters to play with.
374 |
375 |
376 |
380 |
384 |
388 |
389 |
390 |
391 |
392 |
393 |
394 |
395 |
396 | Click handler for highlighted area. Only works when `disableInteraction` is active.
397 |
398 | Useful in case is needed to avoid `onClickMask` when clicking the highlighted element.
399 |
400 |
401 |
405 |
409 |
413 |
414 |
415 |
416 |
417 |
418 |
419 |
420 |
421 | ```js
422 | {
426 | console.log("No interaction at all");
427 | if (clickProps.currentStep < 2) {
428 | e.stopPropagation();
429 | event.preventDefault();
430 | clickProps.setCurrentStep(
431 | Math.min(clickProps.currentStep + 1, clickProps.steps.length - 1)
432 | );
433 | }
434 | }}
435 | >
436 | {/* ... */}
437 |
438 | ```
439 |
440 |
441 |
442 |
443 |
444 | Function to handle keyboard events in a custom way.
445 |
446 |
447 |
451 |
452 |
453 |
454 |
455 | ```js
456 | {
460 | if (e.key === "ArrowRight") {
461 | clickProps.setCurrentStep(
462 | Math.min(clickProps.currentStep + 1, clickProps.steps.length - 1)
463 | );
464 | }
465 | if (e.key === "ArrowLeft") {
466 | clickProps.setCurrentStep(Math.max(clickProps.currentStep - 1, 0));
467 | }
468 | if (e.key === "Escape") {
469 | const nextStep = Math.floor(Math.random() * clickProps.steps.length);
470 | clickProps.setCurrentStep(nextStep);
471 | }
472 | }}
473 | >
474 | {/* ... */}
475 |
476 | ```
477 |
478 |
479 |
480 |
481 |
482 | 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.
483 |
484 |
485 |
486 |
487 |
488 |
489 |
490 |
491 |
492 | Show or hide the Navigation (Prev and Next buttons and Dots) inside
493 | [Popover](/popover).
494 |
495 |
496 |
497 | Show or hide Prev and Next buttons inside [Popover](/popover).
498 |
499 |
500 |
501 | Show or hide the Close button inside [Popover](/popover).
502 |
503 |
504 |
505 | Show or hide the Badge inside [Popover](/popover).
506 |
507 |
508 |
509 | Show or hide dots navigation inside [Popover](/popover).
510 |
511 |
512 |
513 | Activate smooth scroll behavior when steps are outside viewport.
514 |
515 |
516 |
520 | Tolerance in pixels to add when calculating if the step element is outside
521 | viewport to scroll into view.
522 |
523 |
524 |
525 | Configure generic accessibility related attributes like
526 | [aria-labelledby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-labelledby_attribute),
527 | [aria-label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-label_attribute)
528 | for Close button and if show or hide Dot navigation in screen readers.
529 |
530 |
531 |
532 |
533 |
534 |
535 |
536 |
537 |
538 | Option to navigate and show Navigation in right-to-left mode
539 |
540 |
541 |
542 | String to be assigned to the `` element (otherwise an automatic unique
543 | id) of [Mask](/mask) Component
544 |
545 |
546 |
547 | String to be assigned to the `` element (otherwise an automatic
548 | unique id) of [Mask](/mask) Component
549 |
550 |
551 |
552 | Function to control the behavior of [Popover](/popover) when is
553 | transitioning/scrolling from one step to another, calculating with
554 | [Popover](/popover) next position and previous one.
555 |
556 |
560 |
561 |
562 |
563 |
567 | Completelly custom component to render inside the [Popover](/popover).
568 |
569 |
573 |
577 |
578 |
579 |
580 |
581 |
585 |
586 |
587 |
588 |
593 |
594 |
595 |
596 |
597 |
598 |
599 |
600 |
601 |
602 |
603 |
604 |
605 |
606 | ```js
607 | function ContentComponent(props) {
608 | const isLastStep = props.currentStep === props.steps.length - 1;
609 | const content = props.steps[props.currentStep].content;
610 | return (
611 |
612 | {/* Check if the step.content is a function or a string */}
613 | {typeof content === "function"
614 | ? content({ ...props, someOtherStuff: "Custom Text" })
615 | : content}
616 |
627 |
628 | );
629 | }
630 |
631 | const steps = [
632 | /* ... */
633 | ];
634 |
635 | function App() {
636 | return (
637 | ({ ...base, padding: 0 }) }}
641 | >
642 | {/* ... */}
643 |
644 | );
645 | }
646 | ```
647 |
648 |
649 |
650 |
651 |
652 | Element which wraps the Tour. Useful in case is needed to port the Tour into a
653 | [Portal](https://react.dev/reference/react-dom/createPortal).
654 |
655 |
--------------------------------------------------------------------------------
/tour/quickstart.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Installation & Usage"
3 | description: "Tourist Guide into your React Componentss"
4 | icon: "bus-simple"
5 | ---
6 |
7 | ### Install [@reactour/tour](https://www.npmjs.com/package/@reactour/tour)
8 |
9 |
10 |
11 | ```bash npm
12 | npm i -S @reactour/tour
13 | ```
14 |
15 | ```bash yarn
16 | yarn add @reactour/tour
17 | ```
18 |
19 |
20 |
21 | ### Usage
22 |
23 | 1. Add the `TourProvider` at the root of your Application, passing the steps of the elements to highlight during the Tour.
24 |
25 | ```js
26 | import { TourProvider } from "@reactour/tour";
27 |
28 | ReactDOM.render(
29 |
30 |
31 | ,
32 | document.getElementById("root")
33 | );
34 |
35 | const steps = [
36 | {
37 | selector: ".first-step",
38 | content: "This is my first Step",
39 | },
40 | // ...
41 | ];
42 | ```
43 |
44 | 2. Then somewhere down the Application tree, control the Tour using `useTour` hook.
45 |
46 | ```js
47 | import { useTour } from "@reactour/tour";
48 |
49 | function App() {
50 | const { setIsOpen } = useTour();
51 | return (
52 | <>
53 |
54 | Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent at
55 | finibus nulla, quis varius justo. Vestibulum lorem lorem, viverra porta
56 | metus nec, porta luctus orci
57 |
12 | 
17 |
18 | ## Introduction
19 |
20 | Before onboarding products became widespread, I found myself with the need to create a "tour" for new users of different projects, with a nice look and above all with the possibility to interact with existing elements of the page. Thus was born this project in 2017, trying to simplify the logic of [intro.js](https://introjs.com/) with React components, prioritising to use svg and css features.
21 |
22 | With the passage of time and especially with the valuable feedback from users, the package was divided into three main packages that can be used independently: the mask, the popover and the tour (which brings everything together). In addition, the repository has become a single-purpose repository rewritten in typescript.
23 |
24 | Let's start the Tour together!
25 |
26 | ## Packages
27 |
28 |