thisway v0.14.14
- Simple: is simple to use and has no external dependency at all
- Highly customizable: has a powerful API and can be used however you want
- Highlight anything: highlight any (literally any) element on page
- Feature introductions: create powerful feature introductions for your web applications
- Focus shifters: add focus shifters for users
- User friendly: Everything is controllable by keyboard
- Consistent behavior: usable across all browsers (including in-famous IE)
- MIT Licensed: free for personal and commercial use
So, yet another tour library?
No, it is not. Tours are just one of the many use-cases. ThisWay.js can be used wherever you need some sort of overlay for the page; some common usecases could be: e.g. dimming the background when user is interacting with some component i.e. the way Facebook does when you try to create a post, using it as a focus shifter to bring user's attention to some component on page, or using it to simulate those "Turn off the Lights" widgets that you might have seen on video players online, etc.
ThisWay.js is written in Vanilla JS, has zero dependencies and is highly customizable. It has several options allowing you to manipulate how it behaves and also provides you the hooks to manipulate the elements as they are highlighted, about to be highlighted, or deselected.
Installation
You can install it using yarn
or npm
, whatever you prefer.
yarn add thisway.js
npm install thisway.js
Or include it using CDN. If you want a specific version, put it as thisway.js@0.5
in the name
<script src="https://unpkg.com/thisway.js/dist/thisway.min.js"></script>
<link rel="stylesheet" href="https://unpkg.com/thisway.js/dist/thisway.min.css">
Or grab the code from dist
directory and include it directly.
<link rel="stylesheet" href="/dist/thisway.min.css">
<script src="/dist/thisway.min.js"></script>
Usage and Demo
If you are using some sort of module bundler, import the library and the CSS file
import ThisWay from 'thisway.js';
import 'thisway.js/dist/thisway.min.css';
otherwise use the script
and link
tags to import the JavaScript and CSS files.
Highlighting Single Element
You can highlight a single element by simply passing the selector.
const thisway = new ThisWay();
thisway.highlight('#create-post');
A real world usage example for this is: using it to dim the background and highlight the required element e.g. the way Facebook does it when creating a post.
Highlight and Popover
You can show additional details beside the highlighted element using the popover.
const thisway = new ThisWay();
thisway.highlight({
element: '#some-element',
popover: {
title: 'Title for the Popover',
description: 'Description for it',
}
});
Also, title
and description
can have HTML as well.
Positioning the Popover
By default, thisway automatically finds the suitable position for the popover and displays it. You can override it using position
property.
const thisway = new ThisWay();
thisway.highlight({
element: '#some-element',
popover: {
title: 'Title for the Popover',
description: 'Description for it',
// position can be left, left-center, left-bottom, top,
// top-center, top-right, right, right-center, right-bottom,
// bottom, bottom-center, bottom-right, mid-center
position: 'left',
}
});
You can also add offset to the popover position by using the offset
property
const thisway = new ThisWay();
thisway.highlight({
element: '#some-element',
popover: {
title: 'Title for the Popover',
description: 'Description for it',
position: 'bottom',
// Will show it 20 pixels away from the actual position of popover
// You may also provide the negative values
offset: 20,
}
});
Creating Feature Introductions
Feature introductions are helpful when onboarding new users and giving them an idea about different parts of the application; you can create them seamlessly with ThisWay. Define the steps and call the start
when you want to start presenting. User will be able to control the steps using the keyboard or using the buttons on popovers.
const thisway = new ThisWay();
// Define the steps for introduction
thisway.setSteps([
{
element: '#first-element-introduction',
popover: {
className: 'first-step-popover-class',
title: 'Title on Popover',
description: 'Body of the popover',
position: 'left'
}
},
{
element: '#second-element-introduction',
popover: {
title: 'Title on Popover',
description: 'Body of the popover',
position: 'top'
}
},
{
element: '#third-element-introduction',
popover: {
title: 'Title on Popover',
description: 'Body of the popover',
position: 'right'
}
},
]);
// Start the introduction
thisway.start();
You can also hide the buttons and control the introductions programmatically by using the API methods listed below.
Asynchronous Actions
For any asynchronous actions between the transition steps, you may delay the execution till the action completes. All you have to do is stop the transition using thisway.preventMove()
in your onNextClick
or onPreviousClick
callbacks and initiate it manually using thisway.moveNext()
. Here is a sample implementation where it will stop at the second step for four seconds and then move on to the next step.
const thisway = new ThisWay();
// Define the steps for introduction
thisway.setSteps([
{
element: '#first-element-introduction',
popover: {
title: 'Title on Popover',
description: 'Body of the popover',
position: 'left'
}
},
{
element: '#second-element-introduction',
popover: {
title: 'Title on Popover',
description: 'Body of the popover',
position: 'top'
},
onNextClick: () => {
// Prevent moving to the next step
thisway.preventMove();
// Perform some action or create the element to move to
// And then move to that element
setTimeout(() => {
thisway.moveNext();
}, 4000);
}
},
{
element: '#third-element-introduction',
popover: {
title: 'Title on Popover',
description: 'Body of the popover',
position: 'right'
}
},
]);
// Start the introduction
thisway.start();
You can also hide the buttons and control the introductions programmatically by using the API methods listed below.
API
ThisWay comes with several options that you can manipulate to make ThisWay behave as you like
ThisWay Definition
Here are the options that ThisWay understands:
const thisway = new ThisWay({
className: 'scoped-class', // className to wrap thisway.js popover
animate: true, // Whether to animate or not
overlayOpacity: 0.75, // Background overlayOpacity (0 means only popovers and without overlay)
padding: 10, // Distance of element from around the edges
clickOutsideClose: true, // Whether the click on overlay should close or not
clickOutsideMoveNext: false, // Whether the click on overlay should move next
doneBtnText: 'Done', // Text on the final button
closeBtnText: 'Close', // Text on the close button for this step
nextBtnText: 'Next', // Next button text for this step
prevBtnText: 'Previous', // Previous button text for this step
showCtrlBtns: false, // Do not show control buttons in footer
keyboardControl: true, // Allow controlling through keyboard (escape to close, arrow keys to move)
scrollIntoViewOptions: {}, // We use `scrollIntoView()` when possible, pass here the options for it if you want any
onHighlightStarted: (Element) => {}, // Called when element is about to be highlighted
onHighlighted: (Element) => {}, // Called when element is fully highlighted
onDeselected: (Element) => {}, // Called when element has been deselected
onClear: (Element) => {}, // Called when overlay is about to be cleared
onNextClick: (Element) => {}, // Called when moving to next step on any step
onPreviousClick: (Element) => {}, // Called when moving to previous step on any step
});
Note that all the button options that you provide in the thisway definition can be overridden for a specific step by giving them in the step definition
Step Definition
Here are the set of options that you can pass while defining steps setSteps
or the object that you pass to highlight
method:
const stepDefinition = {
element: '#some-item', // Query selector string or Node to be highlighted
popover: { // There will be no popover if empty or not given
className: 'popover-class', // className to wrap this specific step popover in addition to the general className in ThisWay options
title: 'Title', // Title on the popover
description: 'Description', // Body of the popover
showCtrlBtns: false, // Do not show control buttons in footer
doneBtnText: 'Done', // Text on the last button
closeBtnText: 'Close', // Text on the close button
nextBtnText: 'Next', // Next button text
prevBtnText: 'Previous', // Previous button text
},
onNextClick: () => {}, // Called when moving to next step from current step
onPreviousClick: () => {}, // Called when moving to previous step from current step
};
For example, here is how it would look when highlighting a single element:
const thisway = new ThisWay(thiswayOptions);
thisway.highlight(stepDefinition);
And this is how it would look when creating a step by step guide:
const thisway = new ThisWay(thiswayOptions);
thisway.setSteps([
stepDefinition1,
stepDefinition2,
stepDefinition3,
stepDefinition4,
]);
API Methods
Below are the set of methods that are available:
const thisway = new ThisWay(thiswayOptions);
// Checks if the thisway is active or not
if (thisway.isActivated) {
console.log('ThisWay is active');
}
// In case of the steps guide, you can call below methods
thisway.setSteps([ stepDefinition1, stepDefinition2, stepDefinition3 ]);
thisway.start(stepNumber = 0); // Starts driving through the defined steps
thisway.moveNext(); // Moves to next step in the steps list
thisway.movePrevious(); // Moves to previous step in the steps list
thisway.hasNextStep(); // Checks if there is next step to move to
thisway.hasPreviousStep(); // Checks if there is previous step to move to
// Prevents the current move. Useful in `onNextClick` or `onPreviousClick` if you want to
// perform some asynchronous task and manually move to next step
thisway.preventMove();
// Highlights the element using query selector or the step definition
thisway.highlight(string|stepDefinition);
// Reposition the popover and highlighted element
thisway.refresh();
// Resets the overlay and clears the screen
thisway.reset();
// Additionally you can pass a boolean parameter
// to clear immediately and not do the animations etc
// Could be useful when you, let's say, want to run
// a different instance of thisway while one was running
thisway.reset(clearImmediately = false);
// Checks if there is any highlighted element
if(thisway.hasHighlightedElement()) {
console.log('There is an element highlighted');
}
// Gets the currently highlighted element on screen
// It would be an instance of `/src/core/element.js`
const activeElement = thisway.getHighlightedElement();
activeElement.getPositionOnScreen(); // Gets screen co-ordinates of the active element
activeElement.hidePopover(); // Hide the popover
activeElement.showPopover(); // Show the popover
activeElement.getNode(); // Gets the DOM Element behind this element
Note – Do not forget to add e.stopPropagation()
to the click
binding that triggers thisway.
Contributions
Feel free to submit pull requests, create issues or spread the word.
Sponsored By
Thanks to BrowserStack for sponsoring the compatibility testing needs.
License
MIT ©
7 months ago
8 months ago
11 months ago
8 months ago
11 months ago
8 months ago
8 months ago
11 months ago
10 months ago
10 months ago
9 months ago
10 months ago
11 months ago
12 months ago
12 months ago
11 months ago
12 months ago
11 months ago
12 months ago
12 months ago
11 months ago
11 months ago
11 months ago
10 months ago
10 months ago
11 months ago
11 months ago
12 months ago
11 months ago
12 months ago
11 months ago
11 months ago
11 months ago
11 months ago
9 months ago
9 months ago
10 months ago
9 months ago
10 months ago
9 months ago
10 months ago
8 months ago
8 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
9 months ago
10 months ago
9 months ago
10 months ago
10 months ago
9 months ago
10 months ago
9 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
11 months ago
11 months ago
12 months ago
11 months ago
11 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago