Guide to implementing Shepherd JS in vue project

ยท

5 min read

Guide to implementing Shepherd JS in vue project

Shepherd is a JavaScript library that helps you create a step-by-step tour to guide users through your application. It uses Popper.js, which is another open-source library, to render dialogs for each tour "step". You can configure it to start the tour automatically when the user opens the page or when they click on a button.

There are a couple of events that you can use to keep track of the user's actions, such as when they go to the next or previous step, and if they want to complete the tour or quit in the middle. Shepherd can be easily integrated into your application using React, Ember, Angular, Vue.js, ES Modules, or plain JavaScript!

If you're a Vue developer, Vue Shepherd Js is a great option for you. It seamlessly integrates with Vue Js and is a Vue Js wrapper for Shepherd, the JavaScript library for guiding users through your app. With Vue Shepherd Js, you can create guided tours that lead users through various features of your application, explaining functions and capabilities in a user-friendly way.

Getting Started:

  1. Installation:

    Start by installing Vue Shepherd.js using npm:

     npm install vue-shepherd
     <!---or --->
     yarn add vue-shepherd
    
  2. Importing:

    Import Vue Shepherd.js in your Vue file (e.g., HelloWorld.vue):

     <script setup>
       import { useShepherd } from 'vue-shepherd'
     </script>
    

Creating a Simple Tour:

Now, let's create a basic tour to guide users through specific elements of your application.

  1. Define Tour Steps:

    In your Vue component, define the steps of your tour using Shepherd's step definition syntax. Each step has a text property for the message, and a attachTo property to specify the target element

     <script setup>
       import { useShepherd } from 'vue-shepherd'
       import { ref } from 'vue'
        const firstElement = ref(null);
         const secondElement = ref(null);
         const tour = useShepherd({
           useModalOverlay: true, //
         });
         const startTour = () => {
           tour.addSteps([
             {
               attachTo: {
                 element: firstElement.value,
                 on: 'bottom', // placement of the popup box
               },
               title: 'Get Started',
               text: 'Welcome to Your Vue Shepherd.js App',
               classes: 'custom class',
             },
             {
               attachTo: {
                 element: secondElement.value,
                 on: 'top',
               },
               text: '2nd  test',
             }
    
           ]);
           return tour;
         };
     </script>
    
  2. Initiate the Tour:

    Inside your component's mounted lifecycle hook, initiate the tour using Vue Shepherd.js:

     import { mounted } from 'vue';
     <script setup>
         onMounted(() => {
             startTour().start();
         });
     </script>
    

Customization:

Shepherd.js offers several customization options to improve the appearance and functionality of your guided tour. Some common customization options include:

  1. Themes:

    Vue Shepherd.js allows you to apply different themes to your guided tour. The theme determines the overall look and feel of your tour, including the styling of arrows, buttons, and backgrounds. To use a different theme, simply update the classes property in the defaultStepOptions when creating the tour.

    
     <script setup>
       import { useShepherd } from 'vue-shepherd'
       import { mounted } from 'vue';
    
     const tour = useShepherd({
           useModalOverlay: true, //
           defaultStepOptions: {
             classes: 'shepherd-theme-default', // Change theme here
           },
         });
      const startTour = () => {
           tour.addSteps([
             {
               text: 'This is an important feature.',
               attachTo: '.feature-element',
               classes: 'body class',
               arrow: true, //popover arrow. you can customize arrow also
               buttons: [
                 {
                   text: 'Next',
                   action: this.next(), // to go next step
                    clases: 'button class'
                 },
             ]}
         ]);
         onMounted(() => {
             startTour().start();
         });
     </script>
    

    When creating a tour using Vue Shepherd.js, you can add custom classes to individual steps. This feature allows for further styling customization based on the context of each step. You can define custom CSS rules for the specified class to fine-tune the appearance of the step.

  2. Buttons and Events:

    Vue shepherd.js allows for custom buttons and events for each step, providing flexibility to guide users through the tour or trigger specific actions.

     <script setup>
      const startTour = () => {
           tour.addSteps([
             {
               text: 'This is an important feature.',
               attachTo: '.feature-element',
               buttons: [
                 {
                   text: 'Next',
                   action: this.next(), // to go next step
                   classes: 'custom-button-class'
                 },
                  {
                   text: 'Back',
                   action: this.back(), // to go 1 step back
                 },
                 {
                   text: 'Cancel',
                   action: this.cancel(), // Cancel step
                 },
                 {
                   text: 'Skip',
                   action: this.customFunction,
                   classes: 'shepherd-button-secondary', // Customize button style
                 },
               ],
             },
             // Add more steps as needed
             ]);
           ],
         }).start()
      };
     </script>
    

    By defining custom functions like customFunction, you can control the actions associated with each button.

  3. Modal and Overlay Customization:

    You can customize the modal's appearance and overlay displayed during the guided tour. Adjusting properties such as useModalOverlay, modalContainer, and modalHeader allows you to control the layout and styling.

     <script setup>
       import { useShepherd } from 'vue-shepherd'
    
         const tour = useShepherd({
           useModalOverlay: true,
           modalContainer: document.body,
           modalHeader: {
             title: 'Custom Tour Title',
             closeButton: true,
           },
           steps: this.tour,
         }).start()
     </script>
    

    Modify the overlay properties to seamlessly integrate the guided tour into your application's design, enable or disable the close button, and customize the modal title.

Here is a working example on stackblitz.com

https://stackblitz.com/edit/vue-rv27vp?file=src%2Fcomponents%2FHelloWorld.vue,src%2FApp.vue

To add a progress bar, go through this link
https://yonkov.github.io/post/progress-bar-in-shepherd/


Conclusion:

By integrating Vue Shepherd.Js into your Vue.Js project, you can create user-friendly, step-by-step guidance that enhances the user experience and provides valuable information about your application's features.

You can experiment with the customization options to tailor the guided tour to fit your application's layout and user interaction requirements. Vue Shepherd.Js is a powerful tool for developers who want to create intuitive interfaces with minimal effort.

Thanks. Happy coding!

References:

https://github.com/shepherd-pro/vue-shepherd/tree/master

https://shepherdjs.dev/

ย