Targets

A step’s target says which element it points at. Tours break most often because an element was renamed, moved or not rendered yet. This page covers the ways to avoid that.

Name your elements

Add a data-docent attribute to the element and refer to it by name.

<button data-docent="save">Save</button>

{ id: 'save', target: { name: 'save' }, title: 'Save your work' }

This is the most reliable option. Class names change when styles change, and structure changes when layouts change, but an attribute that exists only for the tour stays put. It also tells anyone reading the markup that a tour depends on this element.

CSS selectors

A plain string is a CSS selector. It is handy for elements you cannot add attributes to, such as third-party widgets.

{ id: 'save', target: '#save-button' }

Fallbacks

List several selectors and the first one that matches wins. This keeps a tour working while markup is in flux.

{
  target: {
    name: 'save',
    selectors: ['[data-testid="save"]', 'form button[type=submit]'],
  },
}

The name is tried first, then each selector in order. An invalid selector is skipped rather than throwing. If nothing matches in the page, open shadow roots are searched as well.

Narrowing the search

When a selector matches many elements, within limits the search to a container and nth picks one of the matches, counting from 0.

{ target: { selectors: ['.invoice-row'], within: '#invoices', nth: 2 } }

Elements that appear late

Menus, modals and data-driven lists often render after the step starts. By default, a step whose target is missing is skipped. Ask it to wait instead:

{ id: 'menu-item', target: '#menu-item', onMissing: 'wait', waitFor: 5000 }

The renderer watches the page and shows the step the moment the element appears. If it has not appeared after waitFor milliseconds (3000 by default), the step is skipped.

onMissing	When the target is not there
'skip'	move on to the next step (default)
'wait'	wait up to waitFor ms, then skip
'abort'	end the tour, for steps the tour cannot do without

Try it: the first step asks you to click, and the second waits for an element that appears 600 ms later.

LiveA step that waits for its elementPlay

Reveal after 600 ms

Tip

If an element only appears after the user does something, such as opening a menu, a beforeShow hook can do that for them before the step looks for its target.

Steps without a target

Leave target out and the step shows as a centred card with the page dimmed behind it. Use it to welcome people at the start and to say what comes next at the end.

Finding good targets

The devtools have a target picker: click any element on the page and it suggests selectors ranked by how likely they are to survive changes, and warns about fragile ones such as generated class names.