https://github.com/davvii1/nuxt-driver
Nuxt Module for Driver.js
https://github.com/davvii1/nuxt-driver
driverjs highlight nuxt nuxt-tour
Last synced: 5 months ago
JSON representation
Nuxt Module for Driver.js
- Host: GitHub
- URL: https://github.com/davvii1/nuxt-driver
- Owner: Davvii1
- License: mit
- Created: 2025-06-07T19:55:37.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-17T16:37:34.000Z (about 1 year ago)
- Last Synced: 2025-07-18T20:23:52.055Z (11 months ago)
- Topics: driverjs, highlight, nuxt, nuxt-tour
- Language: TypeScript
- Homepage:
- Size: 152 KB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Nuxt Driver | Driver.js Nuxt Module
[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![License][license-src]][license-href]
[![Nuxt][nuxt-src]][nuxt-href]
A Nuxt 3 module that brings the powerful [Driver.js](https://driverjs.com/) library to your Nuxt applications. Create beautiful, interactive product tours, feature highlights, and user onboarding flows with minimal effort. The module provides a declarative and programmatic API, supporting both CSS selectors and Vue template refs for maximum flexibility. With built-in TypeScript support, reactive state management, and a rich set of features, you can create engaging user experiences while maintaining full control over the tour flow and appearance.
- [✨ Release Notes](/CHANGELOG.md)
## Features
- 🎨 **Fully Typed**: Complete TypeScript support with type definitions
- 🔌 **Auto-import**: Driver.js components and composables are auto-imported
- 🛠️ **Flexible API**: Choose between declarative and programmatic usage
- 🔄 **Reactive State**: Track tour progress and state with reactive properties
- 🎯 **Multiple Targeting**: Use CSS selectors or template refs to target elements
- 🎭 **Custom Components**: Built-in `Tour` component with slot support
- ✨ **Directive Support**: `v-step` and `v-highlight` directives for easy integration
- 🔄 **Progress Tracking**: Built-in progress indicators for multi-step tours
- 🎨 **Customizable**: Full access to Driver.js configuration options
## Quick Setup
1. Add the module to your Nuxt project:
```bash
npx nuxi module add nuxt-driver
```
2. The module will automatically register the necessary components and composables.
## Usage
### 1. Using `useDriver` Composable
The `useDriver` composable provides programmatic control over tours. There are two ways to use it:
#### Method 1: With CSS Selectors
```vue
Start Tour
First step content
Second step content
const { drive, isActive } = useDriver({
showProgress: true,
steps: [
{
element: '#section1',
popover: {
title: 'First Step',
description: 'This is the first step of the tour.'
}
},
{
element: '#section2',
popover: {
title: 'Second Step',
description: 'This is the second step.'
}
}
]
});
const startTour = () => {
drive();
};
```
#### Method 2: With Template Refs
```vue
Start Tour
First step content
Second step content
const step1 = ref(null);
const step2 = ref(null);
const { drive, isActive } = useDriver({
steps: [
{
element: step1,
popover: {
title: 'First Step',
description: 'This is the first step of the tour.'
}
},
{
element: step2,
popover: {
title: 'Second Step',
description: 'This is the second step.'
}
}
]
});
const startTour = () => {
drive();
};
```
### 2. Using the `Tour` Component with `v-step`
The `Tour` component provides a declarative way to create tours using the `v-step` directive. **Note:** The `v-step` directive can only be used inside a `Tour` component.
```vue
Welcome to Our App
Our Amazing Features
{{ isTourActive ? 'Stop Tour' : 'Start Tour' }}
```
### 3. Using `v-highlight` Directive
Highlight important elements anywhere in your app:
```vue
Important Button
const shouldHighlight = ref(true);
```
## Available Properties and Methods
#### `useDriver` Return Value
- `drive(stepIndex?)`: Start the tour or go to a specific step
- `isActive`: Whether the tour is currently active
- `state`: Current driver.js state
- `hasNextStep`: Whether there's a next step
- `hasPreviousStep`: Whether there's a previous step
- `activeIndex`: Current step index
- `activeStep`: Current step configuration
- `previousStep`: Previous step configuration
- `activeElement`: Currently highlighted DOM element
- `previousElement`: Previously highlighted DOM element
#### `Tour` Component
- **Props**:
- `steps`: Array of step configurations (alternative to using `v-step`)
- All other [Driver.js configuration options](https://driverjs.com/docs/configuration) are supported
- **Slot Props**:
- `drive`: Function to start the tour
- `isActive`: Boolean indicating if tour is active
- `activeStep`: Current active step configuration
- `activeIndex`: Current step index
- All other state properties from `useDriver`
### Credits
This module is built on top of the amazing [Driver.js](https://github.com/kamranahmedse/driver.js) library by [Kamran Ahmed](https://github.com/kamranahmedse).
Driver.js is a light-weight, no-dependency, vanilla JavaScript engine to drive user's focus across the page. It's MIT licensed and can be found at [driverjs.com](https://driverjs.com).
[npm-version-src]: https://img.shields.io/npm/v/nuxt-driverjs/latest.svg?style=flat&colorA=020420&colorB=00DC82
[npm-version-href]: https://www.npmjs.com/package/nuxt-driver
[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-driverjs.svg?style=flat&colorA=020420&colorB=00DC82
[npm-downloads-href]: https://www.npmjs.com/package/nuxt-driver
[license-src]: https://img.shields.io/npm/l/nuxt-driverjs.svg?style=flat&colorA=020420&colorB=00DC82
[license-href]: https://www.npmjs.com/package/nuxt-driver
[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js
[nuxt-href]: https://nuxt.com