Tour
A simple, minimalist touring and on-boarding library for javascript
Features
- Supports single page apps, and complex scrollable content
- Responsive & Intelligent
- Automagic Positioning
- Promise Driven Events & Hooks
- Tour does not manipulate or relayer your DOM elements in any way
Installation
Install via npm
$ npm install tour --save
or CDN
https://npmcdn.com/tour@latest/dist/tour.js
https://npmcdn.com/tour@latest/dist/tour.css
Import JS and CSS
import Tour from 'tour'
const Tour = require('tour').default
var Tour = window.Tour.default
@import 'node_modules/tour/dist/tour.css'
Simple Usage
const myTour = {
canExit: true,
nextText: 'Proceed!',
steps: [{
target: '#first-element',
content: 'This is the first step!',
}, {
target: '.some .other .element',
content: 'Blah blah blah. I prefer to show up on the right.',
placement: [ 'right', 'top', 'bottom', 'left' ],
}, {
target: '#menu-element',
content: 'I guess this is a menu!',
}, {
target: '#last-element',
content: 'It is over! :(',
}],
};
Tour.start(myTour)
.then(() => {
console.log('Tour Finished!');
})
.catch(() => {
console.log('Tour Interrupted!')
});
Config
Defaults:
{
canExit: false,
padding: 5,
maxHeight: 120,
maxWidth: 250,
maskVisible: true,
maskVisibleOnNoTarget: false,
maskClickThrough: false,
maskScrollThrough: true
maskColor: 'rgba(0,0,0,.7)'
scrollBox: 'body',
previousText: 'Previous',
nextText: 'Next',
finishText: 'Finish',
showPrevious: true,
showNext: true
animationDuration: 400,
placement: ['bottom', 'right', 'top','left'],
dark: false,
disableInteraction: false,
disableEscExit: false
}
API
.start(tour)
- Starts a Tour
- Params:
- Returns:
- Promise that resolves when the tour is finished or rejected when aborted.
.stop()
- Stops a Tour
- Returns:
- Promise that resolves when the tour is stopped.
.next()
- Goes to the next step in the current tour
- Returns:
- Promise that resolves when the next step is reached
.previous()
- Goes to the previous step in the current tour
- Promise that resolves when the previous step is reached
.goto(index)
Using Promise Event Hooks
You can pass any function that returns a promise to the before
and after
properties for any step. When the promise resolves, the tour moves on accordingly.
Example
var tour = {
steps: [{
target: '#first-element',
content: 'This is the first step!',
}, {
target: '.some .other .element',
content: 'Blah blah blah.',
before: () => {
return new Promise()
}
}, {
target: '#menu-element',
content: 'I guess this is a menu!',
after: () => {
return new Promise()
}
}, {
target: '#last-element',
content: 'It is over! :(',
}]
}
Roadmap & Contributing
All PR's and contributions are more than welcome!