Skip to content
On this page

Tour

Give a tour for new user.

Usage

Simple Usage

Lorem ipsum dolor sit amet consectetur adipisicing elit. Expedita explicabo necessitatibus eius architecto, similique quibusdam sed consequuntur? Esse, praesentium quidem. Dolorem repellendus numquam laudantium nisi labore animi. Iusto maxime exercitationem voluptatem molestias dolorum? Beatae minima deleniti tenetur quo ullam numquam, ab officiis id odio optio ipsam sed, sample text, repellendus, voluptat.
sample
ts
import { createTour } from '@privyid/persona/core'

const tour = createTour()
  .dialog({
    target: '#sample',
    title : 'Step 1',
    text  : 'Hello World'
  })
  .dialog({
    target: '.pager-link.prev',
    title : 'Step 2',
    text  : 'Ini Prev button'
  })
  .dialog({
    target: '.pager-link.next',
    title : 'Step 3',
    text  : 'Ini Next button'
  })

// Start the tour
tour.start()

Advance Usage

ts
const tour = createTour()
  .visit('/design-system/docs/getting-started')
  .dialog('[data-tour="theme-dashboard"]', 'This is tutorial for install persona dashboard theme')
  .delay(100)
  .dialog('[data-tour="theme-docs"]', 'This is tutorial for install persona docs theme')
  .delay(100)
  .visit('/design-system/components/tour/')
  .delay(100)
  .runIf(() => window.matchMedia("(max-width: 700px)").matches, (tour) => {
    return tour
      .dialog('.VPLocalNav > .menu', 'Click this to show sidebar')
  })
  .dialog('[data-tour="start-advance"]', 'Click this to restart the tutorial')

// Start the tour
tour.start()

Defining Tour Stories

You need define stories before can run the tour. There many kind of step you can use to suit with your case.

Show Dialog

Step for showing tour dialog to specific target.

ts
const tour = createTour()
  .dialog({
    target: '[data-tour="sample-dialog"]',
    title : 'This is title',
    text  : 'This is text',
    image : 'https://picsum.photos/400/225',
  })
  // It can also write like this (Shorthand)
  .dialog('#sample', 'This is text', 'This is title', 'https://picsum.photos/400/225')

User Action

Step for trigger event to target element. Available action click, dblClick, tripleClick, type, hover, unhover.

sample
ts
const tour = createTour()
  .click('[data-tour="action-click"]')
  .dblClick('[data-tour="action-dblClick"]')
  .tripleClick('[data-tour="action-tripleClick"]')
  .clear('[data-tour="action-type"]')
  .type('[data-tour="action-type"]', 'Hello World')

Delay

Add delay in millisecond before run to next step.

Timer: 0s
sample
ts
const tour = createTour()
  .click('[data-tour="delay-start"]')
  .delay(5000) // 5s
  .click('[data-tour="delay-stop"]')

Visiting Page

Step for redirecting to some page.

ts
const tour = createTour()
  .visit('/design-system/')
  .dialog('[data-tour="github"]', 'Don\'t forget to give me star on Github')

Conditional Step

If you want run some steps only on some conditions, you can use .runIf, .runElseIf, and .runElse

≥5≥3<3
sample
ts
const number = ref(5)
const tour   = createTour()
  .runIf(() => number.value >= 5, (tour) => {
    return tour
      .dialog('[data-tour="if-more-than-5"]', 'This only run if number >= 5')
  })
  .runElseIf(() => number.value >= 3, (tour) => {
    return tour
      .dialog('[data-tour="if-more-than-3"]', 'This only run if number >= 3 and <= 5')
  })
  .runElse((tour) => {
    return tour
      .dialog('[data-tour="if-less-than-3"]', 'This only run if number < 3')
  })

API

createTour

createTour(options?: TourOptions): TourStory

OptionsTypeDefaultDescription
dismissableBooleantrueEnable dismiss button
prevLabelStringPreviousTour previous button label
nextLabelStringNextTour next button label
dismissLabelStringDismissTour dismiss button label
finishLabelStringFinishTour finish button label
waitTimeoutNumber3000Timeout for waiting target element appear
skipOnErrorBooleanfalseIf true, skip to next step of got an error or timeout
onFinishedFunction-Hook when tour finished

.dialog

.dialog(options: DialogOption): TourStory

OptionsTypeDefaultDescription
targetString-Target query selector, required
textString-Tour dialog body text, required
titleString-Tour dialog title
imageString-Tour dialog image url

Shorthand

.dialog(target: string, text: string, title?: string, image?: string)

.action

.action(options: ActionOption): TourStory

OptionsTypeDefaultDescription
targetString-Target query selector, required
actionString-Tour action, valid value: click, dblClick, tripleClick, type, hover, unhover, clear
paramsArray-Action Parameters

Shorthand

.action(target: string, text: string, ...params: any[]): TourStory

.click(target: string): TourStory

.dblClick(target: string): TourStory

.tripleClick(target: string): TourStory

.hover(target: string): TourStory

.unhover(target: string): TourStory

.clear(target: string): TourStory

.type(target: string, text: string): TourStory

.delay

.delay(duration: number): TourStory

.visit

.visit(url: number, backURL?: string): TourStory

.runIf

.runIf(condition: () => boolean | Promise<boolean>, tourCallback: (tour: TourStory) => TourStory): TourStory

.runElseIf

.runElseIf(condition: () => boolean | Promise<boolean>, tourCallback: (tour: TourStory) => TourStory): TourStory

.runElse

.runElseIf(tourCallback: (tour: TourStory) => TourStory): TourStory

.start

Start the tour

.start(): Promise<void>

.stop

Stop the tour

.stop(): Promise<void>

Released under the MIT License.