Persona

Appearance

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.

Copyright © 2022 Privy Identitas Digital