usablica / intro.js

Lightweight, user-friendly onboarding tour library

Intro.js

User Onboarding and Product Walkthrough Library

Where to get

You can obtain your local copy of Intro.js from:

1) This GitHub repository, using git clone https://github.com/usablica/intro.js.git

2) Using yarn yarn add intro.js

3) Using npm npm install intro.js --save

4) Download it from CDN (1, 2)

How to use

Intro.js can be added to your site in three simple steps:

1) Include intro.js and introjs.css (or the minified version for production) in your page. Use introjs-rtl.min.css for Right-to-Left language support.

CDN hosted files are available at jsDelivr (click Show More) & cdnjs.

2) Add data-intro and data-step to your HTML elements. To add hints you should use data-hint attribute.

For example:

<a href='http://google.com/' data-intro='Hello step one!'></a>

See all attributes here.

3) Call this JavaScript function:

introJs().start();

Optionally, pass one parameter to introJs function to limit the presentation section.

For example introJs(".introduction-farm").start(); runs the introduction only for elements with class='introduction-farm'.

Documentation

Please visit Documentation.

Using with:

Intro.js has many wrappers for different purposes. Please visit Documentation for more info.

Build

First you should install nodejs and npm, then first run this command: npm install to install all dependencies.

Now you can run this command to minify all static resources:

npm run build

Contributors ✨

Afshin Mehrabani 💻 📖

bozdoz 💻 📖

Support/Discussion

• Stackoverflow

License

Commercial license

If you want to use Intro.js for a commercial application, theme or plugin the commercial license is the appropriate license. With this option, your source code is kept proprietary. Purchase a commercial license at introjs.com

Open-source license

GNU AGPLv3

intro.js's Issues

Feature idea: Highlight table columns

Imagine trying to highlight the content of a table "This column contains info about X", wouldn't that be nice to do?

I have to admit I am not sure how to solve the problem where colspans would break away from the intro.js highlight if it is even possible to do this to begin with…

Last Position on started

Hello...

I want to make it, how to show last step on started. example user closed on second step, all steps about 5 step. So, when user open this intro will begin on second step on first step.

Popup Width is too small for navigation menus

Popup width is too smal when we have tour on the navigation element which text is too small or icon only.

introjs-overlay doesn't cover full screen

since the html and body elements are only ~930px tall, the introjs-overlay element doesn't grow any larger than that. When you are on a large screen monitor, you see the rest of the page below the overlay

Mask layer not full-screen

Mask layer not full-screen when _addOverlayLayer(targetElm == document.body); Add overlayLayer.style.height = document.height + 'px'; to hack

Different sites between steps? (Intro through the whole Online Shop)

Thank You for the really great Script!

I´m using Magento and my Customers are older People, between 50-80 years old. I wan´t to add the intro-button on the homepage of the store and show steps for the customers trought whole online shop. From Homepage, trought the Categorie View, Detail View and the Cart. To explain the Customer the whole Online Shop. That would be an incredible feature, and a whole new step for the e-commerce landscape!!! I think the problem will be, when the customer use the script and (as example), the last step on homepage is #5 he click to the step 6 and the script go to the category-view. And after hat in the category view it must be step #6 open....I hope you understand what I mean. This is everything, thx from Germany

Use prefix data-intro-*

To be more copatible with others all data-attributes should use a prefix and build like data-intro-*

After completing the intro remove the keys from the action "step".

If this is not done - a mistake, immediately begins a new intro, but without the overlay

Support for mobile pages?

Will this be supported on mobile devices? Seeing strange issues on android on screen resolution changes during device rotation

Uncaught TypeError: Object function (targetElm) ... has no method 'start'

Uncaught TypeError: Object function (targetElm) {
if (typeof (targetElm) === "object") {
//Ok, create a new instance
return new IntroJs(targetElm);

} else if (typeof (targetElm) === "string") {
  //select the target element with query selector
  var targetElement = document.querySelector(targetElm);

  if(targetElement) {
    return new IntroJs(targetElement);
  } else {
    throw new Error("There's no element with given selector.");
  }
} else {
  return new IntroJs(document.body);
}

} has no method 'start'

Included CSS and JS

called introJs.start();

Lauching by an element ID or by class group not working

I've made a simple test in intro.js example ... changing in the Chrome DevTools the button action

<a class="btn btn-large btn-success" href="javascript:void(0);" onclick="javascript:introJs('.test').start();">Show me how</a>

and a step information , adding a class :

<div class="span6 test" data-step="2" data-intro="Ok, wasn't that fun?">
      <h4>Easy to Use</h4>
      ...

Any ideas what can it be?

Remove minified version from example

It's hard to compare a working example to a broken local version when the working example is minified.

Add option to change opacity level of the overlay, maybe even the color

If the html element is already white then the overlay obscures everything behind it making it hard to see the original elements (For example if the page is using white font). Having the ability to control the opacity will help overcome this issue.

Keyboard access lock focus request

It would be nice if the keyboarding was locked focus into the active elements, as illustrated in the example at http://jqueryui.com/dialog/#modal-form

In the current implementation, all the web page items are still in tab order and users that require keyboard access have to tab through all elements to get back to the dialog. If this was implemented, people who require keyboard access, including screen reader and software screen magnifier users, would have a better experience.

Wonderful tool - best of luck and thanks for sharing it :)

Position of the step

It would be good to scroll the browser's scrollbar to a position where user can easily the step info. e.g. if one step is at the bottom of the page and the next one is up to the top of the page, it would be awesome that the lib could scroll to the position.

Could it support set the `step numer` element position

Could it support set the step numer element position , because when intro a full document height/widht element , the step numer is on the top, overflow and hidden.

navbar fixed top, positioning issue

Hello,

First of all, thank you very much for this amazing plugin!
I'm using Twitter bootstrap for the layout of my site and I put one of my steps in a navbar fixed top. Making the the number step cut off... (see princtscreen).

Any chance we could also change the position of the step number for such cases?

Thanks,
Denis

Bug: Position of tooltip text is wrong if successive elements have different amount of text

The sample html has similar text sizes and hence all the tooltiptext elements are roughly the same size. If you change the text size between successive elements (switching between 1 line and 2 or more lines) then the new position of the tooltiptext is wrong since _getOffset ends up using the old size to determine position.

Test case html is here - https://github.com/deepakprabhakara/intro.js/blob/master/example/index.html

Diff - https://github.com/deepakprabhakara/intro.js/commit/9df12f89e1b31519866b0374c95930fa602cfd0f

Doesn't work on absolute positioned elements

The script adds a helper class to target elements which changes the z-index of that item (so it comes to the top). The problem is to change z-index, it has to change the positioning to position: relative;.
When adding this helper class to a absolute positioned element, it changes the page layout.

Solution: the script should check the position property before adding the helper class. if it already has a position, it should just change the z-index, not the positioning itself.

idea : hide or disable "back" and "next" button on first and last slide

as I told everything on title

Unify all data-* attributes, consider ajax-requested (and html) content

First of all - big thanks for intro.js, it looks very promising.

I have a few suggestions for you:

1. Maybe it would be better if data-* attributes were written like this:

data-intro-text, data-intro-step

in case of some new options and to prevent future conflicts with existing markup (another libraries) OR you can take JSON way:

data-intro='{ "step": 1, "text": "..." }'

1. It would be very cool to have an option to load step content asynchronously via ajax from source defined in attribute:

data-intro-source / "source" property in JSON

or from source defined in script:

introJs({ source: "/get_content.php" }).start(); // sends request to get_content.php with automatic "step" parameter depending on current step

1. Allow html ajax response to be parsed as a content and using hidden elements as source:

data-intro-id / "id" property in JSON

and anywhere in document:

<div id="my-content" hidden>lorem ipsum</div>

Adding options: fullScreen and group for .setOptions()

New features:

• intro.js running just for defined selectors
• fullscreen option(default: true) for overlay layer

see the README for more information
https://github.com/maurodias/intro.js#introjssetoptionsoptions

Add a "<- Prev" link to the overlay

So that the user can navigate back.

CSS suggestions (linear gradients etc.)

Gradients

background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,#ff3019), color-stop(100%,#cf0404)); /* Chrome,Safari4+ */
...
background: -ms-linear-gradient(top, #ff3019 0%,#cf0404 100%);
...
filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='#ff3019', endColorstr='#cf0404',GradientType=0 ); /* IE6-9 */

Since both Chrome and Safari already support new syntax (-webkit-linear-gradient and unprefixed version very soon), I consider -webkit-gradient code needless.

IE10 supports UNprefixed version of linear-gradient; -ms- prefix was introduced in developer preview versions, so it's still supported in full IE10 release, but there is no need to use it (unless you wish to make IE10-specific gradient without unprefixed declaration).

filter - throw it away. One word - performance. In such a case this matters more for me than tip-top appearance.

Look at this table http://caniuse.com/#feat=css-gradients - My bold suggestion for background is:

background: #ff3019; /* oldies, not such a horror if IE9 won't get gradient... */
background: -webkit-linear-gradient(#ff3019, #cf0404); /* current Chrome and Safari */
background: linear-gradient(#ff3019, #cf0404); /* allmost every browser nowadays */

I removed direction and percentage too, because they were just describing defaults.

Transitions

Same as gradients - at least remove -ms-transition declaration.

IE9- text shadow filter

Ok, if it's good for better readability, leave it there, but I would choose text and background colors that don't need to depend on text-shadow and throw that filter away.

Font family

font-family: Arial, verdana, tahoma;

Missing typeface declaration (sans-serif) - but personally I wouldn't override document's fonts at all.

Color definitions
You have "rgb(0, 0, 0)", "gray", or "#ff3019" - wouldn't it be nicer to have only one style ("#000000" is a way) of describing colors (without alpha channel)?

That's all, take whatever you want from it and thank you for your time :-).

Multi page intro

How would you get an intro to continue across pages?

Intro goes off screen for elements at right edge of page

With elements that are on the right edge of the screen the intro overlay will be displayed off screen in Chrome 26. A fiddle displaying this behavior:

http://jsfiddle.net/3vcbr/

The introjs-helperLayer element cover the Introduced element

When give element style position: absolute and z-index,the introJS's introjs-helperLayer element has covered the Introduced element.

Does this works with tabs(anchors) ?

Hi, can you tell if this work with elements in another tab ? Im using bootstrap.
Thanks,
Jcorreia

Release patch

Hey guys, great work you've been doing thus far!

It might be a good idea to do a patch release soon, with all the changes that have been done recently, a 0.1.1 its certainly worth it, and will allow external gems (i.e. introjs-rails) to keep up to date with the latest master, without screwing up version numbers on the gem.

Callback option to give more usability

I think it would be better if we add callback for any steps. It's actually not difficult. Example would be like like

<div id="user_info" data-intro="Bla Bla Bla" data-step="4" 
 onstepstart="function1" onstepend="function2"> </div>

<script>
var function1 = function(){
     $("#user_info").animate({color: "red"}, 500);
}

var function2 = function(){
     $("#user_info").css({color: "black"});
}

</script>

Provide direct access to different steps

It will be better to provide access to different steps

Please make it happen in next build,

I'm enjoying using this, Thanks. :)
👍

Page doesn't scroll enough to show instructional callout

On the site at http://usablica.github.com/intro.js/ clicking the "Show me how" button starts a demonstration. Step 2 of the demonstration should cause the browser to scroll down enough to both show the entire highlighted area and the instructional callout beneath it.

In both Chrome 27.0.1430.0 dev and Safari 6.0.2 (8536.26.17) on OS X 10.8.2, starting with the scroll at the very top of the page, the page only scrolls down maybe 30-40 pixels when transitioning from step 1 to step 2, not nearly enough to show the entire highlighted area, and not even enough to indicate there is an instructional callout beneath it.

Tooltip position do not work

Tooltip position do not work @chrome 25.0.1364.172 m windows
Set the data-position='left' in the example page but it doesn't work, the tooltip still at the bottom, is my wrong?

introJS version : 0.1.0

could support multiple language or custom language

Hi, i am a Chinese. I try intro.js, it is cool and useful and i want to use it on our production, but it is regretful that it not supports custom language now, because our customers are also Chinese.

Doesn't work on children of absolute/relative positioned elements

Source for test here: http://pastebin.com/ztyuYjK7
More info about stacking contexts here: http://tinyurl.com/cnxomh5

I think the problem is that the introjs elements are added to the global stacking context, regardless of the stacking context of the target. This causes the overlay and helper layers to be stacked on top of the desired target, instead of underneath.

z-index bug on targetElement means that it appears above the helperNumber

The easiest way to see this bug is on the demo: http://usablica.github.com/intro.js/

Just open up the Web Inspector and then apply a background colour to the target element then you will see that it in fact is above the the helper number.

See the below screenshot for an example:

Done Instead Next

اگه تو مرحله ی آخر به جای دکمه ی Next → دکمه ی done وجود داشته باشه و skip تو مرحله ی آخر حذف بشه بهتره. من پیشنهادمو بر پایه ی نسخه ی 0.2.1 و نسخه ای که روی گیت هاب قرار داره گفتم.

Doesn't work on IE8

Popup and overlay Works ! The designated area remains under the overlay.

Does Intro support Twitter Bootstrap?

Hello,

I wan to know, does Intro support with Twitter Bootstrap? Is it compatible? thanks

deal with scroll panes

Hello,

I appreciate a lot your work, I implement it in a web application project and have some issues, I thought it could be useful to share it.

Our application got a lot of panel that have toolbars. I wanted to make a step with an element inside a scrollable panel, but it failed. That is what I have fixed here.

_getOffset method lack consideration for scrollpane

Firstly, there is a mistake with the _getOffset method, because it doesn' t consider scroll panel. Indeed if you want it to work with them, you have to substrat the scrollx and scrolly value, because scrolling make the element inside the scrollpane go up relatively to the window viewport.
I didn't try to fix it, instead I use jQuery which does the work pretty well.

highlight an element in a scrollpane

Secondly if the system is able to scroll the window screen to make the element visible, it can't scroll other panel.

I write a method which adjust the scrolling of all the parent of the element to make it visible. Again this function use jQuery.

I assume you choose to not work with jQuery, so my contribution is not so much helpfull, but you can get inspired if you want to solve this minor issues.

the source code of my fixes and a example are visible here

thanks you!

intro.js & jQueryUi

It seems there is some problems with jQueryUI.
Is quelq'un to find out why?

Here is an example of the problem I found
http://jsfiddle.net/cHxvz/

Press enter to skip to next

I want to be able to press enter to go to the next step. I can to go from step 2 to step 3, but not from step one to step two.

Future Request

Thank you Usablica team,It's fantastic.
I have some suggestions for getting it better.
I think the active step should be at the center of view-able screen and if the tooltip is out of view-able screen it should be moved to top,right or left side of active step.

Port intro.js to Dart

Yea I know this is not an issue as such, but I think intro.js is a nifty project, and I would love to have it available in Dart. :)

Feature: Add steps through programmatic configuration

Hi,

I really appreciate your project as I had exactly the same kind of plugin already on my todo list to be implemented in the next weeks, but now I'm thinking about using/extending yours.

So far your plugin is awesome, I'd just have a couple of additional requirements/ideas:

Possibility to programmatically specify steps

I've looked at your code and there is a "private" variable _introSteps which holds the information about the different steps. My idea would be to add a setter to be able to configure the steps programmatically. This is especially needed when your app is being composed by a different number of widgets, meaning you don't have 1 single place with all the HTML code s.t. you could add data-annotations.

As such I'd like to control the steps from some global mechanism after the (single-page JavaScript) app has been fully initialized. This could look like

var intro = new introJS();
intro.initSteps([
  {
    element: $('.js-1stEl'),
    intro: 'the intro text',
    position: ...,
    ...
  },
  {
    element: $('.js-2ndEl'),
    intro: 'Another element...',
    position: ...,
    ...
  }
]);

Activator Functions

Assume you have multiple tabs and in your intro you'd like to highlight different things on these tabs to the user. That would mean you have to somehow activate the regions prior to showing the intro tooltip.

I thought about implementing this by giving the possibility to associate an activator function like

intro.initSteps([
  {
    element: $('.js-1stEl'), //an element inside the tab page
    intro: 'the intro text',
    onToolTipShow: function(element) { //would be called before showing the tooltip
        $('#myTab a:last').tab('show'); //do your action, i.e. load the bootstrap tab page
    }
  }
]);

What's your opinion on these features?? I'd be willing to implement and contribute them, I just wanted to first clarify your point of view.

Support for RequireJS AMD and Common JS module

As of now, introJS is on the Window object.
Can you give a support for RequireJS AMD and Common JS.

enter key for navigating will be called twice

try on Chrome Version 25.0.1364.172 m
seems that enter key input will be handled after the first round is finished ...

Highlight doesn't move on page resize

The highlight doesn't move correctly if you resize the browser window.

Bug: Doesn't work with SVG

I'm developing a site where the navigation is entirely drawn in SVG.

I have tried including the intro.js elements in my a tags, in my tags, and surrounding them with divs, to no avail. Each time, the intro text loads in the upper left corner.

I have pushed an example of this to http://gendale.net

More Info Edit: I made gendale call intro.js onload. The script is still aware the location of the SVG element -- it scrolls down to the bottom of the page. The tooltip, however, still loads in the top left of the page. Perhaps the ability to set the origin of the tooltip would be a simple fix for this?

Can open multiple copies

This is related to my desire to press enter to go to the next. Currently, if I click the button to open the help, and then press enter, the button gets a second click event and a second instance of the help opens.

This is on the demo at http://usablica.github.com/intro.js/