A game-quality, interactive tutorial library for Vue 3 applications
npm install vue-nudgebash
npm install vue-nudge
or
yarn add vue-nudge
or
pnpm add vue-nudge
`
Quick Start
$3
`vue
`
$3
`typescript
import type { TutorialConfig } from 'vue-nudge'
export const myTutorialConfig: TutorialConfig = {
id: 'my-first-tutorial',
showProgress: true,
allowClose: true,
steps: [
{
id: 'welcome',
title: 'Welcome! 👋',
description: 'Let me show you around',
placement: 'center'
},
{
id: 'click-button',
target: '[data-tutorial="my-button"]',
title: 'Click This Button',
description: 'Go ahead, click it!',
placement: 'bottom',
blockInteractions: false,
waitForAction: {
event: 'button-clicked',
timeout: 30000
}
},
{
id: 'explore',
target: '[data-tutorial="feature-panel"]',
title: 'Explore This Feature',
description: 'This panel contains important information',
placement: 'right',
allowSkipTo: ['final-step']
},
{
id: 'final-step',
title: 'All Done! 🎉',
description: 'You're ready to go!',
placement: 'center'
}
],
onComplete: () => {
console.log('Tutorial completed!')
},
onClose: () => {
console.log('Tutorial closed')
}
}
`
$3
`vue
Feature content here
`
$3
`vue
`
API Reference
$3
`typescript
interface TutorialConfig {
id: string // Unique identifier for this tutorial
steps: TutorialStep[] // Array of tutorial steps
showProgress?: boolean // Show progress indicator (default: true)
allowClose?: boolean // Allow closing tutorial (default: true)
onComplete?: () => void // Callback when tutorial completes
onClose?: () => void // Callback when tutorial is closed/skipped
}
`
$3
`typescript
interface TutorialStep {
id: string // Unique step identifier
title: string // Step title
description: string // Step description (supports HTML)
target?: string // CSS selector for highlighted element
placement?: 'top' | 'bottom' | 'left' | 'right' | 'center'
blockInteractions?: boolean // Block clicks on other elements
waitForAction?: {
event: string // Event name to wait for
timeout?: number // Optional timeout in ms
}
allowSkipTo?: string[] // Step IDs that can be skipped to
popoverClass?: string // Additional CSS class for popover
onEnter?: () => void | Promise
onExit?: () => void | Promise
}
`
$3
`typescript
const tutorial = getTutorial()
// Start a tutorial
await tutorial.start(config: TutorialConfig)
// Navigation
await tutorial.next() // Go to next step
await tutorial.previous() // Go to previous step
await tutorial.skipTo(stepId: string) // Skip to specific step
// Control
tutorial.complete() // Mark tutorial as complete
tutorial.close() // Close/cancel tutorial
// Events
tutorial.triggerAction(actionName: string, data?: any)
tutorial.on(event: string, handler: Function)
tutorial.off(event: string, handler: Function)
// Utility
tutorial.isCompleted(tutorialId: string): boolean
tutorial.resetCompletion(tutorialId: string)
`
Advanced Usage
$3
`typescript
{
id: 'expand-menu',
target: '[data-tutorial="menu"]',
title: 'Open the Menu',
description: 'Click to expand this menu',
waitForAction: {
event: 'menu-expanded',
timeout: 30000 // 30 second timeout
}
}
`
Then in your component:
`vue
`
$3
Allow users to skip sections of the tutorial:
`typescript
{
id: 'beginner-tips',
title: 'Tips for Beginners',
description: 'Some helpful advice...',
allowSkipTo: ['advanced-features', 'final-step']
}
`
This will show skip buttons like "Skip to Advanced Features →"
$3
Override default styles with CSS variables or by targeting classes:
`css
.tutorial-popover {
--tutorial-primary-color: #ff1493;
--tutorial-bg-color: #1e293b;
--tutorial-border-radius: 12px;
}
.tutorial-overlay__glow {
/ Customize glow effect /
}
`
$3
The tutorial automatically tracks size and position changes:
`vue
`
The spotlight and popover will automatically adjust when the panel expands!
Examples
Check out the examples/ directory for complete working examples:
- Basic tutorial
- Multi-step onboarding flow
- Form validation tutorial
- Feature tour
TypeScript Support
Full TypeScript support with comprehensive type definitions:
`typescript
import type {
TutorialConfig,
TutorialStep,
TutorialState,
TutorialEventType
} from 'vue-nudge'
``