Getting started

A tour walks someone through your interface one element at a time. Each step dims the page, spotlights one element, and explains it in a small popover with Back and Next buttons. Docent handles the positioning, scrolling, keyboard and focus. You write the words and decide which element each step points at.

1. Install the package for your stack.

   Vanilla

   pnpm add @docentjs/dom

   React

   pnpm add @docentjs/react

   Vue

   pnpm add @docentjs/vue

   Svelte

   pnpm add @docentjs/svelte

   One package is enough. The framework packages include the web renderer and the engine, and re-export everything you need, so in a React app every import comes from @docentjs/react.

2. Describe the tour.

   A tour is a plain object: an id and a list of steps. defineTour adds type checking and stamps the schema version.

   tours.ts

   import { defineTour } from '@docentjs/dom'
   
   export const welcome = defineTour({
     id: 'welcome',
     options: { showProgress: true },
     steps: [
       { id: 'intro', title: 'Welcome', body: 'This takes about a minute.' },
       { id: 'sidebar', target: { name: 'sidebar' }, title: 'Navigation', placement: 'right' },
       { id: 'new', target: '#new-project', title: 'Create a project', advance: { on: 'click' } },
       { id: 'done', title: 'All set' },
     ],
   })

   A step without a target shows as a centred card, which suits a welcome and a goodbye. The last-but-one step uses advance: { on: 'click' }, so it moves on when the person clicks the button instead of pressing Next.

3. Mark the elements the steps point at.

   <aside data-docent="sidebar">…</aside>
   <button id="new-project">New project</button>

   target: { name: 'sidebar' } finds data-docent="sidebar". A plain string such as '#new-project' is a CSS selector. Names are the better habit: they survive redesigns, and they say plainly that an element is part of a tour.

4. Start it.

   import { createTour } from '@docentjs/dom'
   import { welcome } from './tours'
   
   createTour(welcome).start()

   createTour connects the web renderer, saves progress to localStorage, and follows client-side navigation. Call resume() instead of start() to continue from where the person left off.

Here is the same tour running on this page:

LiveThe tour from the steps abovePlay

SidebarNew project

Showing tours automatically

createTour(...).start() shows a tour when you call it. To show tours on their own, for example once to new users on their first visit, hand them to the tour manager instead:

import { createDocent } from '@docentjs/dom'

const docent = createDocent({ tours: [welcome, invoices] })
docent.identify(user.id, { plan: user.plan })

Each tour’s trigger, conditions and frequency then decide who sees it and when.

Where to go next

ConceptsHow tours, the engine and the renderer fit together.

TargetsPoint steps at elements reliably, including ones that load late.

Tour managerMany tours, shown to the right people at the right time.

ThemingMake the popover match your product.