Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/alex-oleshkevich/vue-introjs

intro.js bindings for Vue.
https://github.com/alex-oleshkevich/vue-introjs

introjs vue

Last synced: 10 days ago
JSON representation

intro.js bindings for Vue.

Awesome Lists containing this project

README 

        
# vue-introjs

intro.js bindings for Vue.



## Installation

### Add package

```bash

yarn add vue-introjs



# or via npm:

npm i vue-introjs

```



### Install plugin

```javascript

import VueIntro from 'vue-introjs';

Vue.use(VueIntro);

```



#### Use CDN version of introJs

Make sure you have installed and attached [`intro.js`](http://introjs.com/docs/getting-started/install) scripts and styles to the page.

This plugin **does not** come with intro.js built-in.



The motivation of it is to give the developer more control on intro.js versions.



#### Use with webpack and vue-cli

Install required dependency:

```bash

yarn add intro.js



# or via npm:

npm i intro.js

```



As this plugin relies on global `introJs` variable, webpack should provide it:

```javascript

// webpack.config.js

{

    plugins: [

        new webpack.ProvidePlugin({

            // other modules

            introJs: ['intro.js']

        })

    ]

}



// attach CSS

// SomeComponent.vue

import 'intro.js/introjs.css';

```



If you are using `vue-cli` this can be done with the following lines in your `vue.config.js`:



```javascript

// vue.config.js

const webpack = require('webpack');



module.exports = {

  configureWebpack: {

    plugins: [

      new webpack.ProvidePlugin({

        'introJs': ['intro.js']

      })

    ]

  },

}

```



#### Use with vue-cli and webpack template

Add to your `src/main.js` something like this for global, or per SFC like above:

```javascript

import VueIntro from 'vue-introjs'

Vue.use(VueIntro)



import 'intro.js/introjs.css';

```

then add into the `plugins` sections of `build/webpack.dev.conf.js` and `build/webpack.prod.conf.js` the `new webpack.ProvidePlugin({` section from above.



Don't forget to install `intro.js` though and save it (via yarn or npm). The `webpack.ProvidePlugin` will pull it in, so no need to `import introJs from 'intro.js'` in `src/main.js`



#### Use with NuxtJs

Make sure you install `vue-introjs` and `intro.js` then create a Nuxt plugin in `/plugins`

```javascript

//plugins/vue-introjs.js`

import Vue from 'vue'

import VueIntro from 'vue-introjs'

import 'intro.js/introjs.css'



Vue.use(VueIntro)

```



then add it to your `nuxt.config.js` list of plugins

```javascript

//nuxt.config.js`

plugins: [

    // ..

    { src: '~plugins/vue-introjs.js', mode: 'client' },

]

```



Finally register `introjs` by adding it as a webpack plugin and you're set

```javascript

//nuxt.config.js

import webpack from 'webpack'



export default {

    build: {

        // ..

        plugins: [

            new webpack.ProvidePlugin({

                introJs: ['intro.js'],

            }),

        ],

    }

}

```



## Contents

The plugin extends Vue with a set of directives and `$intro()` constructor function.



## Define steps and hints

Directives, to define introductional steps:

### Steps



```html

The tooltip text of step.



```



```html

Optionally define the number (priority) of step.



```



```html

Optionally define a CSS class for tooltip.



```



```html

Optionally append a CSS class to the helperLayer.



```



```html

Optionally define the position of tooltip, `top`, `left`, `right`, `bottom`, `bottom-left-aligned` (same as `bottom`), `bottom-middle-aligned`, `bottom-right-aligned` or `auto` (to detect the position of element and assign the correct position automatically). Default is `bottom`.



```



```html

Optionally define the element to scroll to, `element` or `tooltip`. Default is `element`.



```



```html

To disable interactions with elements inside the highlighted box, `true` or `false` (also `1` or `0`).



```



More about [intro steps](http://introjs.com/docs/intro/attributes/)



### Hints

Directives, to define hints:



```html

The tooltip text of hint.



```



```html

Optionally define the position of hint. Options: `top-middle`, `top-left`, `top-right`, `bottom-left`, `bottom-right`, `bottom-middle`, `middle-left`, `middle-right`, `middle-middle`. Default: `top-middle`.



```



More about [hints](http://introjs.com/docs/hints/attributes/)



Also refer `example` directory for live examples.



## Usage

Once all steps are defined, call `start()` or `showHints()` to start the show:

```javascript

// SomeComponent.vue

{

    mounted() {

        this.$intro().start(); // start the guide

        this.$intro().showHints(); // show hints

    }

}

```



## Configuration

When the defaults are not enough, then fine tuning is required.

Construct a new `introJs` instance and configure in own way:

```javascript

this.$intro('#intro-farm'); // //start introduction for element id='intro-farm'

this.$intro().addStep({}); // Add a new step to introJs programmatically.

```



Basically, `$intro()` returns a new `introJs` instance which then can be configured usign it's [API](http://introjs.com/docs/intro/api).



## Registering callbacks

Just call `this.$intro().`. Example:

```javascript

// SomeComponent

this.$intro().oncomplete(function () {

    console.log('completed');

});

```



## Autostart

If tour should start automatically when all directives loaded,

add `v-intro-autostart="true"` directive.

Also extra configuration required for plugin:

```javascript

import VueIntro from 'intro.js';

Vue.use(VueIntro, {

    waitTimeout: 400

});

```



For hints use `v-intro-autostart:hints="true"`.



### How it works

The plugin starts a timer with `waitTimeout`.

Every `v-intro` directive restarts that timer. This lets the plugin to wait for async components, router views or other components to load before tour will be autostarted.



### Configure intro.js instance

Add `v-intro-autostart.config` next to `v-intro-autostart` with intro.js configuration object as an argument.

That object then passed to `introJs(obj)` constructor.

```html



```



### Listening for intro.js events

It is possible to add event listeners to automatically started tour.

The format is:

```

v-intro-autostart:on.=""

```

where `event-name` is any of intro.js supported hooks (see [intro.js hooks](http://introjs.com/docs/intro/api/#introjsoncompleteprovidedcallback)) for more details.

Same applies to hints.



**Note**, the plugin defines two more events, designed to work with the autostart feature:

`onautostart` and `onautostarthints`. These callbacks receive two arguments: `element` and current `introjs` instance.



For example:

```html





```



## Conditional steps and hints

When it is required to bind intro only when some expression evaluates to `true`,

use `v-intro-if` directive.

It accepts any valid expression that evaluates to either `true` or `false`:

```html



```



Note, that `v-intro-if` directive must go after `v-intro`.



## Credits

1. [http://introjs.com](http://introjs.com)

2. Gabriel J Perez Irizarry