Steps and advancing

A step is one stop on the tour: an element, a short explanation, and a way to continue. Good steps say one thing. If a step needs three paragraphs, it is probably two steps.

Content

{
  id: 'invoices',
  target: { name: 'invoices-tab' },
  title: 'Invoices',
  body: 'Click **Invoices** to see everything you have billed.',
  format: 'markdown',
  media: { type: 'image', src: '/help/invoices.png', alt: 'The invoices list' },
}

• title is the heading. Keep it short, ideally under six words.
• body is plain text by default.
• With format: 'markdown', a safe subset is rendered: bold, italic, code, links, paragraphs and line breaks.
• media adds an image or a video above the text. Always give images an alt.

Note

Raw HTML is never injected, even with markdown on. Tours loaded from a server or written in a builder are safe to render as they are.

Placement

placement says where you would like the popover. It is a preference, not an order:

placement: 'auto' | 'top' | 'right' | 'bottom' | 'left'
         | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end'
         | 'left-start' | 'left-end' | 'right-start' | 'right-end'

If the preferred side has no room, the popover flips to the opposite side, then tries the other two, and finally slides along the edge to stay on screen. -start and -end align the popover with one end of the element instead of its middle.

On screens narrower than 480 px, the popover docks to the bottom of the screen as a sheet, and the page scrolls so the element is not hidden behind it. Change the width with the renderer’s sheetBreakpoint, or set it to 0 to turn the sheet off.

Moving on

By default the person presses Next. The advance field lets the tour follow what they actually do instead, which teaches far better than reading.

advance	The step moves on when
'button'	the person presses Next (default)
{ on: 'click' }	they click the target
{ on: 'input', match: '^\\S+@' }	what they type matches the regular expression
{ on: 'event', name: 'saved' }	your code calls controller.notify('saved'), or docent.track('saved') with the manager
{ on: 'element', target: '#menu' }	an element appears
{ on: 'delay', ms: 4000 }	the time passes

Normally the spotlighted element cannot be clicked, so nobody triggers an action by accident mid-tour. Click and input steps make it clickable automatically. For any other step, set interaction: 'allow' to let people use the element.

LiveClick, type, and a blocked elementPlay

ContinueDelete everything

Buttons and wording

Hide buttons on one step:

buttons: { back: false, skip: false, close: false, next: false }

Change the wording for a whole tour with options.labels, or for every tour at once with the renderer’s labels:

options: {
  labels: { next: 'Continue', back: 'Previous', skip: 'Not now', done: 'Finish', progress: 'Step {current} of {total}' },
}

Progress

With showProgress on, the popover shows how far along the person is. The count includes every step, even ones later skipped by a condition, so the numbers never jump backwards mid-tour.

Skipping steps for some people

A step-level condition skips that step when it is false, for example a step about admin settings that only admins should see:

{ id: 'billing', condition: { type: 'trait', key: 'role', op: 'eq', value: 'admin' }, … }

Conditions are covered in Triggers and conditions.