shepherd-pro / vue-shepherd

A Vue wrapper for the site tour library Shepherd

vue-shepherd

vue-shepherd is built and maintained by Ship Shape. Contact us for web app consulting, development, and training for your project.

This is a Vue wrapper for the Shepherd, site tour, library.

npm install vue-shepherd --save

Usage

Composition API (suggested)

<template>
  <div ref="el">
    Testing
  </div>
</template>

<script setup>
  import { ref, onMounted } from 'vue'
  import { useShepherd } from 'vue-shepherd'

  const el = ref(null);

  const tour = useShepherd({
    useModalOverlay: true
  });
  
  onMounted(() =>  {
    tour.addStep({
      attachTo: { element: el.value, on: 'top' },
      text: 'Test'
    });

    tour.start();
  });
</script>

Option API

To use vue-shepherd with Option API you have to install the plugin which will add the '$shepherd' function to your vue app.

import { createApp } from 'vue';
import VueShepherdPlugin from 'vue-shepherd';
import '~shepherd.js/dist/css/shepherd.css';

createApp().use(VueShepherdPlugin).mount('#app');

<template>
  <div ref="el">
    Testing
  </div>
</template>

<script>
  import { defineComponent } from 'vue'

  export default defineComponent({
    data(){
      return {
        tour: null
      }
    },

    methods: {
      createTour(){
        this.tour = this.$shepherd({
          useModalOverlay: true
        });

        this.tour.addStep({
          attachTo: { element: this.$refs.el, on: 'top' },
          text: 'Test'
        });
      }
    },

    mounted(){
      this.createTour();
      this.tour.start();
    }
  });
</script>

SSR

For server side rendering project, you should import the vue-shepherd.ssr.js file.

import VueShepherd from 'vue-shepherd/dist/vue-shepherd.ssr.js';

Directives

WIP

vue-shepherd's Issues

How to create offset to attached element?

Hello!

I'd like to create a tour with arrows, that does not draws over the target. By default if I enable arrows, it will be drawn a bit over the element it is attached to.
In the docs, there is a popperOptions, and Issue 874 have the same option, that I came up with, but neither applying to default defaultStepOptions in the tour, or in the step does anything.
My second thought would be to create a margin around shepherd-element class, but that makes the element not properly aligned.

Some snippets of the code, in case I messed up something:

defaultStepOptions: {
        popperOptions: {
          modifiers: [{ name: 'offset', options: { offset: [10, 12] } }]
        },

tour.addStep({
        popperOptions: {
          modifiers: [{ name: 'offset', options: { offset: [10, 12] } }]
        },

So how could I move the step popup a bit father from the selected element, so it does not draws over it?

I'm using the vue-shepherd wrapper.

Error: Cannot read property "add" of undefined

Hello, I'm trying a very simple test of vue-shepherd and I'm getting the following error after clicking on the first "Next" button associated with first Step ('Welcome to the JMRL Staff-Portal Tour.'). Part of the issue is when this is still available as the main Vue prototype, but I don't think that's it (and the same problem occurs if I use this.$el or that.$el in the first Step.

Console code and code for App.vue follows (I've scrubbed some mapActions from the <script> section because they aren't pertinent.

Uncaught TypeError: Cannot read property 'add' of undefined
    at Step._show (shepherd.esm.js:5063)
    at Step.show (shepherd.esm.js:4891)
    at Tour.show (shepherd.esm.js:5724)
    at Tour.next (shepherd.esm.js:5671)
    at HTMLButtonElement.<anonymous> (shepherd.esm.js:2670)
_show @ shepherd.esm.js:5063
show @ shepherd.esm.js:4891
show @ shepherd.esm.js:5724
next @ shepherd.esm.js:5671
(anonymous) @ shepherd.esm.js:2670

/**
App.vue
*/

<template>
  <div>
    <TheNavbar ref="app-navbar-id" />

    <router-view />
  </div>
</template>

<script>
import { TheNavbar } from '@/components/Nav/index.js'
import { mapActions } from 'vuex'

export default {
  name: 'App',
  data() {
    return {}
  },

  components: {
    TheNavbar,
  },

  async created() {
    console.log('App created', new Date().getTime())
    try {
      debugger
      await this.loadLoginStates()
      debugger
    } catch (e) {
      console.log(e)
    }
  },

  mounted() {
    console.log('App mounted', new Date().getTime())
    let that = this

    this.$nextTick(() => {
      const tour = this.$shepherd({
        defaultStepOptions: {
          classes: 'shadow-md bg-purple-dark',
          scrollTo: true,
        },
        useModalOverlay: true,
      })

      tour.addSteps([
        {
          attachTo: { element: this.$el, on: 'top' },
          classes: 'example-step-extra-class',
          buttons: [{ text: 'Next', action: tour.next }],
          text: 'Welcome to the JMRL Staff-Portal Tour.',
        },
        {
          attachTo: { element: that.$refs['app-navbar-id'], on: 'bottom' },
          classes: 'example-step-extra-class',
          buttons: [
            {
              text: 'Next',
              action() {
                tour.next()
                return this.$router.push({ name: 'hr-leave-user' })
              },
            },
          ],
          text: 'And continue with the tour!',
        },
      ])

      tour.start()
    })
  }
}
</script>

not published on npm/yarn yet ?

Hey there! I'm trying to install this but it says it doesn't exist..

https://www.npmjs.com/package/vue-shepherd

https://registry.yarnpkg.com/vue-shepherd

I'm not sure how this works.. did you forget to publish it or something?

Thanks!

Failed to find shepherd.css

Going crazy, so hope someone out here can help!

I've installed the vue-shepherd plugin as well as the shepherd.js plugin.

"shepherd.js": "^8.1.0", "vue-shepherd": "^0.2.1",

and I can SEE the shepherd.css file in ../node_modules/shepherd.js/dist/css/shepherd.css

But when I try and import the file I'm getting:
ERROR in ./app/javascript/app.vue?vue&type=style&index=0&lang=css& (./node_modules/css-loader/dist/cjs.js??ref--3-1!./node_modules/vue-loader/lib/loaders/stylePostLoader.js!./node_modules/postcss-loader/src??ref--3-2!./node_modules/vue-loader/lib??vue-loader-options!./app/javascript/app.vue?vue&type=style&index=0&lang=css&) Module build failed (from ./node_modules/postcss-loader/src/index.js): Error: Failed to find '../node_modules/shepherd.js/dist/css/shepherd.css'

Any idea where I've gone astray??

modal disappears on second step

Using shepherd and vue-shepherd. First run through the tour, everything works fine. But if I run it a second time, the modal appears on the first step only and then disappears on the second step. Tried with and without modalContainer param.

Would be nice to add type declarations for typescript

I got it working by adding a .d.ts containing just declare module vue-shepherd but it would be good to include a more complete type declaration for typescript users.

Nuxt 3 implementation

Please can you provide specific instructions on how to implement in nNuxt 3 as well??

Cannot read properties of undefined (reading 'ES_BUILD')

Uncaught TypeError: Cannot read properties of undefined (reading 'ES_BUILD')

// package.json
{
  "scripts": {
    "nuxt": "3.4.3",
    "nuxt-gtag": "^0.5.7",
    "nuxt-lodash": "^2.4.1",
    "nuxt-vitest": "^0.6.12"
  },
  "dependencies": {
    "vue-shepherd": "^3.0.0"
  },
}

// vue-shepherd.client.ts

import VueShepherdPlugin from 'vue-shepherd';

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(VueShepherdPlugin)
})

floatingUIOptions does not work?

I'm trying to use offset because the default placement does not account for the arrow, and places it on top of the target element. However, none of the values I place in floatingUIOptions gets used by the tour modal; I also tried placement to see if anything would work besides the offset middleware. It seems none of the values

I saw a few closed issues related to this in the main repo: https://github.com/shipshapecode/shepherd/issues?q=is%3Aissue+floatinguioptions+is%3Aclosed. But I am wondering if the issue lies in vue-shepherd for me, since those seemed to be solved.

Individual steps do not set their own floatingUIOptions in my tour, they're only declared here:

const tour = useShepherd({
    useModalOverlay: true,
    defaultStepOptions: {
        ...
        floatingUIOptions: {
            placement: 'top',
            middleware: [offset(18)],
        },
    },
});

Guidance on beforeShowPromise and placing tour steps in Vuex Module ?

Hello,

Currently working on a scenario where I would like to take my tour steps our of the main App.vue code and place them in a separate file in order to make code easier to maintain/manage based on modular architecture.

I'm currently using VUEX for the project, so wanted to try and create a guidedtour module and add my steps in there, however I also use the beforeShowPromise in order to change up the UI for the tour steps, make sure options are Visible prior to guiding users through those steps.

Does anyone have any good guidance on best practices to be able to excise the tour steps, and yet still use the beforeShowPromise to reference the vue instance and be able to change variables / layout on the main apps variables ?

How can we get the promise to reference a this. / self of the vue app instance when defined in a separate module.
Appreciate any pointers, examples.

need upgrade package version to 6

current 5.0.0-beta.

How to handle complete event in Vue 2?

Hello :)

I am looking for a way to handle the complete event in Vue 2. I am using "vue-shepherd": "3.0.0", and using it as follows:

<script>
	import { useShepherd } from 'vue-shepherd'
	import 'shepherd.js/dist/css/shepherd.css'

	export default {
		name: 'ShepherdGuide',
		data() {
			return {
				tour: null
			}
		},
		created() {
			this.createTour()
		},
		mounted() {
			setTimeout(() => {
				this.tour.start()
			}, 500)
		},
		methods: {
			createTour() {
				this.tour = useShepherd({
					useModalOverlay: true,
					defaultStepOptions: {
						classes: 'shadow-md bg-purple-dark shepherd-theme-custom',
						scrollTo: true,
						// modalOverlayOpeningRadius: 4,
						when: {
							show() {
								console.log('---hit show')
								console.log('curr step: ', this.tour.currentStep)
							},
							hide() {
								console.log('---hit hide')
							},
							back() {
								console.log('--- hit back')
							},
							next() {
								console.log('--- hit next')
							},
							cancel() {
								console.log('--- hit cancel')
							},
							complete() {
								console.log('--- hit complete')
							},
							start() {
								console.log('--- hit start')
							},
							active() {
								console.log('--- hit active')
							},
							inactive() {
								console.log('--- hit inactive')
							},
							done() {
								console.log('--- hit done')
							}
						},
						cancelIcon: {
							enabled: true,
							label: 'Testing description'
						}
					}
				})

				this.tour.addSteps([
					{
						id: 'step-1',
						title: 'Step 1 title',
						text: 'Testing Shepherd tour - first step',
						attachTo: { element: '.tour-guide-1', on: 'right' },
						buttons: [
							{
								text: 'Next',
								action: this.tour.next
							}
						]
					},
					{
						id: 'step-2',
						title: 'Step 2 title',
						text: 'Testing Shepherd tour - second step',
						attachTo: { element: '.tour-guide-2', on: 'right' },
						buttons: [
							{
								text: 'Prev',
								action: this.tour.back
							},
							{
								text: 'Next',
								action: this.tour.next
							}
						]
					},
					{
						id: 'step-3',
						title: 'Step 3 title',
						text: 'Testing Shepherd tour - last step',
						attachTo: { element: '.tour-guide-3', on: 'right' },
						buttons: [
							{
								text: 'Prev',
								action: this.tour.back
							},
							{
								text: 'Finish',
								action: this.tour.complete
							}
						]
					}
				])
			},
		}
	}
</script>

In this case, when I use the this.tour.complete, it doesn't fire up the complete event, thus, it doesn't print the message in the console. If I make the finish button to use this.tour.hide action, it successfully hits the method and shows the message in the console. Unfortunately, that is not what I want, because it hits hide every time I go to the next step, thus, I will have to make some additional checks if that is the last step or not.

Am I doing something wrong or I have to use the hide event to handle the Finish button in the last step ?

How to use in SSR

Hi, I want to use this plugin in nuxtjs mode ssr. Can anyone please help me how to do resolve this issue?

Not Loading

I am getting the error:

"TypeError: _this.$shepherd is not a function"

Dont I have to import this plugin some how? Your docs to show you having to do any of that.

Vue 3 Support

Hi, are there any plans for Vue 3 support?

Get the latest version of Shepherd ??

I just installed this library in a project and I noticed that it is installing Shepherd version 8.0.1.

Would it be possible to release an update of this library to include the latest version of Shepherd (10.0.0)?

Does the current version support vue2?

When referencing, it prompts entry.js:11 Uncaught TypeError: Cannot set properties of undefined (setting '$shepherd')

How to make popups look like Shepherd?

I thought importing this Vue wrapper would allow the popups to look like the demo on Shepherd's page. Am I needing to add certain CSS classes in a config somewhere? I am importing the CSS file as mentioned in the docs. I did notice that the demo popup that comes in this repo is incomplete as well.

Fail to import using Vite + Vue 3

When trying to import in a project which uses Vite and Vue 3, it fails.

import { useShepherd } from 'vue-shepherd';

During runtime, it fails with an error:

Uncaught ReferenceError: process is not defined

Which leads to:
if ('false' === process.env.ES_BUILD) {

Here, process doesn't exit. We should use a different value as indicated in https://stackoverflow.com/questions/71083110/vue-uncaught-referenceerror-process-is-not-defined, but of course we cannot change it unless rebuilding the project

I was able to fix this by adding a statement in vite.config.js:

define: {
        'process.env': {}
    }

Is it possible to add support for Vite, or add some info in documentation regarding this?

process is not defined at entry.js

Hi! I'm trying to use vue-shepherd on a Vue 3 project using vite. Unfortunately, I got this error on load : process is not defined

Am I missing something in the config? I just copy pasted the code provided in the Readme. As I'm using composition API, I don't see any extra step to get it working.

Vite uses import.meta.env instead of process.env, maybe that's related?

Packages version:

"vue": "^3.2.45",
"vue-shepherd": "^2.0.1"
"@vitejs/plugin-vue": "^4.0.0",
"vite": "^4.0.0"

Repro link : https://stackblitz.com/edit/vitejs-vite-ruw4zb?file=src/App.vue

Thanks!

Error in Vite project when using Shepherd.js with process.env.ES_BUILD

Description:

I am encountering an issue in my Vite project when trying to use Shepherd.js, specifically related to the process.env.ES_BUILD check in the entry.js file. The error occurs on line 19, column 17.

Error Location:

AT entry.js:19:17

import Shepherd from 'shepherd.js';

...

if ('false' === process.env.ES_BUILD) {
  // Error occurs here
  let GlobalVue = null;
  if (typeof window !== 'undefined') {
    GlobalVue = window.Vue;
  } else if (typeof global !== 'undefined') {
    GlobalVue = global.Vue;
  }
  if (GlobalVue) {
    GlobalVue.use(plugin);
  }
}

Steps to Reproduce:

1. Create a Vite project.
2. Include Shepherd.js and the provided entry.js file.
3. Run the project.

Expected Behavior:

The project should run without errors.

Actual Behavior:

The error mentioned above is thrown, indicating an issue with the process.env.ES_BUILD check.

Environment:

• Vite version: "^4.3.9",
• Shepherd.js version: "^3.0.0"
• Node.js version: v20.6.1

What is the best practice to cancel tour if user click back browser button?

I can prevent user for clicking other button component that route to outside current component using overlay.

But if user clicking back browser button, the tour is still running.

so i use navigation guard and search the classname like this

beforeRouteLeave (to, from, next) {
    const tourOverlay =  document.getElementsByClassName('shepherd-modal-is-visible')[0]
    const tourStep = document.getElementsByClassName('shepherd-enabled')[0]

    if (tourOverlay && tourStep) {
      tourOverlay.remove()
      tourStep.tourStep()
    }

    next()
}

Is there a best practice to achieve this?

[Question] Is there any way to add vue component instead of html string in the text of tour object?

Hi, I am building a tour guide using vue shepherd and my requirements contains more dynamic logics to apply on the tour guide, Rightnow I am achieving my goals using html string. But is there any way that I just plug my whole vue component here so I can handle all of my logics in a separate component.

How to set border radius for highlighted element?

I want to set border radius for highlighted element,
try using modalOverlayOpeningRadius in options is not working
when i try

document.querySelector('#shepherdModalMaskOpening').setAttribute('rx', 50);

like in shepherd-pro/shepherd#250 (comment) , got an error

vue.esm.js?a026:628 [Vue warn]: Error in mounted hook: "TypeError: Cannot read properties of null (reading 'setAttribute')"

Global Tour instance

Can there be a global instance for the tour?
For example to initialize it once in the App.js and then just use it with different steps in different components.

I think with the "regular" js Version there is a global isntance.
Can I just put it in the State?

[QUESTION] Is there a way to add a progress bar?

This is within Shepherdjs but I don't see how to add this into vue-shepherd.

Still active?

Thanks for the wrapper! I was wondering whether this repo is actively managed? Is it synchronized with the Sheperd library releases?

Calling Vue methods inside of Tour instances

Is there a way to call this.$store/router/other Vue instance methods while inside of a tour instance? For example I'd like to be able to go to a specific route in a when.hide or on beforeShowPromise but this seems to be specific in those spots to the new shepherd tour being built. I get errors saying that this.$store is undefined.

I was thinking maybe call, apply, or bind may work, but I'm not sure how to use those effectively for this situation.

Is "useShepherd" in last version not working?

I tried to use vue-shepherd with Composition API, but I got a such error: "Uncaught (in promise) TypeError: (0 , vue_shepherd__WEBPACK_IMPORTED_MODULE_3__.useShepherd) is not a function". Just wondering, how I can solve it, and maybe anybody else get such an error too?