tour-guide-turbham

Vue Tour Guide Component

A customizable tour guide component for Vue 3 applications that highlights elements and guides users through different steps.

Table of Contents

• Installation
• Usage
  • Props
  • Events
  • Example
• Components
  • GuideWrapper
  • Guide
• Author

Features

• Customizable steps with dynamic content
• Smooth scrolling to elements
• Highlighting elements with tooltips
• Configurable positioning of tooltips
• Automatic progression through steps
• Resize handling

Installation

npm install tour-guide-turbham

Usage

1. To use the tour guide in your Vue project, import the component and the CSS file:

import { createApp } from "vue";
import App from "./App.vue";
import "tour-guide-turbham/dist/style.css";

const app = createApp(App);

app.mount("#app");

2. Import the TourGuide component into your Vue application.

<template>
  <div id="app">
    <TourGuide :steps="steps" :startTour="true" :showGuideInterVal="4500" />
    <!-- Other content -->
  </div>
</template>

<script setup>
import { ref } from "vue";
import TourGuide from "./components/TourGuide.vue";

const steps = ref([
  {
    component: "StepComponent1",
    attachTo: { element: "#element1", on: "bottom" },
    stepFunction: () => console.log("Step 1 action"),
  },
  {
    component: "StepComponent2",
    attachTo: { element: "#element2", on: "right" },
    stepFunction: () => console.log("Step 2 action"),
  },
  // Add more steps as needed
]);
</script>

Each step is an object that can contain these properties:

const step = {
  component: Component,
  attachTo: {
    element: "#element3",
    on: "right",
  },
  text: "Click here to view all user settings",
  width: "max-w-[206px]", // Tailwind CSS styles
  offset: 48, // Guide offset from attached element
  stepFunction: () => console.log("Step action"), // Function ro run in current step
};

Props

Prop	Type	Required	Default	Description
steps	Array	Yes	-	Array of step objects defining the tour steps
startTour	Boolean	No	false	Automatically start the tour on mount
startOnMount	Boolean	No	true	Start the tour when the component is mounted
showGuideInterVal	Number	No	4500	Time interval in milliseconds between steps

Events

The component provides several events to handle tour actions. These events can be used within the scope of the tour guide:

Event Name	Description
nextStep	Fired when the tour is ended.
endTour	Fired when the next step is reached.

Example

Here is a complete example of using the TourGuide component in a Vue 3 application:

<template>
  <div id="app">
    <TourGuide :steps="steps" :startTour="true" :showGuideInterVal="4500" />
    <div id="element1">Step 1 target element</div>
    <div id="element2">Step 2 target element</div>
  </div>
</template>

<script setup>
import { ref } from "vue";
import TourGuide from "./components/TourGuide.vue";

const steps = ref([
  {
    component: "StepComponent1",
    attachTo: { element: "#element1", on: "bottom" },
    stepFunction: () => console.log("Step 1 action"),
  },
  {
    component: "StepComponent2",
    attachTo: { element: "#element2", on: "right" },
    stepFunction: () => console.log("Step 2 action"),
  },
  // Add more steps as needed
]);
</script>

Components

GuideWrapper

The GuideWrapper component is used to wrap the content of each step in the tour.

Guide

The Guide component is used to display the content of each step in the tour. You can use it in the steps array by specifying it as the component.

const steps = ref([
  {
    attachTo: {
      element: "#step1",
      on: "bottom",
    },
    text: "This is step 1",
    component: "Guide",
  },
  {
    attachTo: {
      element: "#step2",
      on: "top",
    },
    text: "This is step 2",
    component: "Guide",
  },
  // Add more steps as needed
]);

Credits

This NPM package was developed by Tobiloba Odukoya.