v-onboarding

v-onboarding is a lightweight, fully-typed onboarding component designed for Vue 3. It enables developers to create interactive product tours and user guides. Key features include:

• SVG Overlay: Precise element highlighting with customizable padding and border radius.
• Smart Positioning: Automatic tooltip placement powered by Popper.js.
• Customizable UI: Full control over appearance using Vue slots.
• Lifecycle Hooks: Support for beforeStep and afterStep to handle asynchronous operations.
• Focus Management: Optional focus trap for improved accessibility.
• TypeScript Support: Comprehensive type definitions for a better developer experience.

v-onboarding is a fully-typed, customizable onboarding component designed for Vue 3. It provides a guided tour experience with the following core capabilities:

• SVG Overlay: Precise element highlighting with customizable padding, border radius, and overlay opacity.
• Smart Positioning: Automatic tooltip positioning that adapts to viewport boundaries using Popper.js.
• Full Customization: Complete control over step appearance using Vue slots.
• Lifecycle Hooks: Support for beforeStep and afterStep hooks to handle async operations, analytics, or state management.
• Focus Management: Optional focus trap to ensure keyboard navigation remains within the tour interface.
• TypeScript Support: Comprehensive type definitions for a robust developer experience.

Lifecycle hooks allow you to execute custom logic at specific points during the onboarding tour. You can define these hooks within the on property of a step configuration. Hooks can be asynchronous and are useful for data fetching, UI synchronization, or analytics tracking.

There are two primary step hooks:

• beforeStep: Executes before a step is displayed. Use this for preparing the UI or loading necessary data.
• afterStep: Executes after a user leaves a step. Use this for cleanup or tracking step completion.

{
  on: {
    beforeStep: async ({ index, step, direction }) => {
      // Logic before step
    },
    afterStep: ({ index, step, direction }) => {
      // Logic after step
    }
  }
}

When providing custom content via slots, you must wrap your custom UI inside the VOnboardingStep component. This ensures that the onboarding system maintains proper positioning and overlay functionality for your custom elements.

<template>
  <VOnboardingWrapper ref="wrapper" :steps="steps">
    <template #default="{ step, next, isLast }">
      <VOnboardingStep>
        <div class="my-custom-tooltip">
          <h3>{{ step.content?.title }}</h3>
          <button @click="next">
            {{ isLast ? 'Finish' : 'Next' }}
          </button>
        </div>
      </VOnboardingStep>
    </template>
  </VOnboardingWrapper>
</template>

<script setup>
import { VOnboardingWrapper, VOnboardingStep } from 'v-onboarding'
</script>

A tour is composed of an array of Step objects. Each step defines where the tooltip should attach, what content to display, and optional behaviors or lifecycle hooks.

Each step follows this structure:

• attachTo.element: A CSS selector, a getter function, or a Vue template ref used to target the element for the tooltip.
• content: An optional object containing title and description strings.
• options: Optional StepOptions for customizing placement, scrolling, and overlay.
• on: Optional lifecycle hooks (beforeStep, afterStep) to run logic during the step transition.

interface Step {
  attachTo: {
    element: string | (() => Element | null) | Ref<Element | null>
  }
  content?: {
    title?: string
    description?: string
  }
  options?: StepOptions
  on?: {
    beforeStep?: () => void | Promise<void>
    afterStep?: () => void | Promise<void>
  }
}

If you prefer not to use the Nuxt module, you can manually register the components via a client-side plugin. Ensure the file has a .client.ts suffix to prevent server-side execution errors.

// plugins/v-onboarding.client.ts
import { VOnboardingWrapper, VOnboardingStep } from 'v-onboarding'
import 'v-onboarding/dist/style.css'

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.component('VOnboardingWrapper', VOnboardingWrapper)
  nuxtApp.vueApp.component('VOnboardingStep', VOnboardingStep)
})

If you require complete control over the UI layout and want to handle positioning yourself (e.g., using a Modal or a Teleport), you can omit the VOnboardingStep wrapper.

Warning: By omitting VOnboardingStep, you lose automatic Popper.js positioning and the SVG overlay functionality.

<template>
  <VOnboardingWrapper ref="wrapper" :steps="steps">
    <template #default="{ step, next }">
      <!-- No VOnboardingStep wrapper - you handle positioning -->
      <Teleport to="body">
        <div class="my-modal-overlay">
          <div class="my-modal">
            {{ step.content?.title }}
            <button @click="next">Continue</button>
          </div>
        </div>
      </Teleport>
    </template>
  </VOnboardingWrapper>
</template>

You can use the index prop from the default slot to conditionally render different UIs for specific steps. For steps where you want the default behavior, you can use VOnboardingStep without any children or with a v-else block.

<template>
  <VOnboardingWrapper ref="wrapper" :steps="steps">
    <template #default="{ step, next, exit, index }">
      <!-- Custom UI for step 3 (index 2) -->
      <VOnboardingStep v-if="index === 2">
        <MySpecialTooltip
          :title="step.content?.title"
          @next="next"
          @close="exit"
        />
      </VOnboardingStep>

      <!-- Default UI for all other steps -->
      <VOnboardingStep v-else />
    </template>
  </VOnboardingWrapper>
</template>