walkthrough.vue

walkthrough.vue is a lightweight, customizable Vue.js plugin that provides an interactive walkthrough experience for your Vue applications. Built with TypeScript and SCSS, this plugin allows you to guide users through key features and elements of your app, enhancing their understanding and engagement.

Table of Contents

• Installation
• Usage
  • Basic Setup
  • Template Structure
  • SCSS Styling
• Configuration
  • Example Configuration
• API
• Customization
• Examples
• Contributing
• License

Installation

You can install the plugin via npm:

npm i walkthrough.vue

Alternatively, you can use the plugin directly from the dist folder by including the JavaScript and CSS files in your project:

<link rel="stylesheet" href="path/to/dist/style.css">
<script src="path/to/dist/walkthrough.umd.js"></script>

Or from the source code here

Usage

Basic Setup

First, import and register the plugin in main.ts

import { createApp } from 'vue'
import App from './App.vue'
import Walkthrough from "walkthrough.vue"; // Notice this is the package name 😅 not a vue component

const app = createApp(App)
app.use(Walkthrough) // Register the plugin
app.mount('#app')

Then import and initialize the walkthrough in your Vue component:

<script setup lang="ts">
import walkthrough, { type Options, type Step } from 'walkthrough.vue';
import { reactive } from 'vue';

const steps = reactive<Step[]>([
  {
    element: '#step1',
    title: 'Welcome',
    content: 'This is the first step of our guided tour.',
  },
  // Add more steps here
]);

const options = reactive<Options>({
  prevText: 'Previous',
  nextText: 'Next',
  finishText: 'Finish',
});

const startWalkthrough = () => {
  walkthrough.init(options, steps);
};
</script>

HTML Structure

Ensure your template elements are structured correctly to be targeted by the walkthrough:

<template>
  <div id="step1">Welcome to the interactive guide.</div>
  <div id="step2">Here's a key feature of our website.</div>
  <!-- More elements -->
  <button @click="startWalkthrough">Start Walkthrough</button>
</template>
<!-- More elements -->

SCSS Styling

The plugin uses SCSS for custom styles. You can include the provided style.css in your project or import the SCSS files from source code directly to customize the styles:

@import 'path/to/plugin/src/styles.css';

Configuration

You can configure the walkthrough with the following options:

• nextText: (string, optional) customize the Next button text in the step.
• prevText: (string, optional) customize the Previous button text in the step.
• finishText: (string, optional) customize the Finish button text in the step.

And you can configure each step in the walkthrough with the following options:

• selector: (string) The CSS selector of the element to highlight.
• title: (string, optional) The title to display in the modal or tooltip.
• content: (string) The content to display in the modal or tooltip.
• nextText: (string, optional) customize the Next button text in the step.
• prevText: (string, optional) customize the Previous button text in the step.
• finishText: (string, optional) customize the Finish button text in the step.
• nextCallback: (function, optional) A function to call when the next button is clicked.
• prevCallback: (function, optional) A function to call when the previous button is clicked.

Example Configuration

const steps = reactive<Step[]>([
    {
        element: '#step1',
        content: 'Welcome to our site! Let’s start with the basics.',
    },
    {
        element: '#step2',
        title: 'Features',
        content: 'This is a key feature you should know about.',
        nextCallback: () => console.log('Step 2 completed!'),
    },
]);

Customization

The appearance of the walkthrough can be easily customized via SCSS. Key classes you might want to style include:

• .walkthrough-modal
• .walkthrough-title
• .walkthrough-content
• .walkthrough-close-container
• .walkthrough-highlight
• .walkthrough-buttons
• #walkthrough-steps
• .walk-through-start button

For example:

.walkthrough-content {
  background-color: #fff;
  border-radius: 10px;
  box-shadow: 0 4px 10px rgba(0, 0, 0, 0.1);
}

Examples

Here’s an example of the walkthrough in action:

const steps = reactive<Step[]>([
  {
    element: '#step1',
    title: 'START',
    content: 'Start here!',
  },
  {
    element: '#step2',
    content: 'Next, check out this feature.',
  },
  {
    element: '#step3',
    title: 'FINISH',
    content: 'Finally, see how everything works together.',
  },
]);

const startWalkthrough = () => {
  walkthrough.init({}, steps);
};

Navigation Shortcuts

You can use keyboard shortcuts to navigate through the walkthrough:

• Left Arrow: Go to the previous step.
• Right Arrow: Go to the next step.

Contributing

Contributions are welcome! Please fork the repository and submit a pull request with your improvements. Make sure to follow the existing code style and include tests for any new features or bug fixes.

License

This project is licensed under the MIT License. See the LICENSE file for details.