Tour

Step-by-step feature onboarding with a fullscreen overlay and target highlighting. Supports 12-direction placement with overflow flipping, scroll-following repositioning, mask/form customization, keyboard navigation, async steps, hints beacons and a "Don't show again" memory.

Basic usage

Start the tour

Start tour

Highlighted area 1

Highlighted area 2

Example

Tour events

oas-step carries detail: { index, current, total, next, prev }; closing events (cancel/finish/close/skip/destroy) carry detail: { index, total } (oas-cancel additionally carries a source identifying the cancel origin).

Step events

Start tourNot started

Highlighted area 1

Highlighted area 2

Example

Controlled step and visibility

Both open and current are controlled attributes: an external button / JS sets open to start the tour, and sets current to jump directly to a given step (no need to click through).

Controlled open / current

Start tour (set open)Jump to step 2 (current=1)Jump to step 3 (current=2)Finish (remove open)

Controlled highlight area 1

Controlled highlight area 2

Controlled highlight area 3

Example

Placement and arrow

placement supports 12 directions (top/bottom/left/right × start/end/center) plus center; it auto-flips along the main axis when space is insufficient. arrow="false" hides the arrow.

12 directions and auto-flip

Right placement (placement=right)Auto-flip at bottomNo arrow (arrow=false)

Right placement target

Multi-direction target

Bottom target (viewport edge)

Example

Scroll to target and repositioning

When the target is off-screen the tour scrolls to it (scroll-into-view-options is passed through; scroll-padding sets the target's scroll-margin). During the tour the highlight and popup follow scroll/resize automatically (auto-reposition, enabled by default).

Scroll to target and scroll-follow

Start tour (target below the fold)

Below-the-fold target 1 (scrolled to)

Below-the-fold target 2

Example

Overlay and form

mask="false" disables the overlay (non-modal; the rest of the page stays interactive during the tour); mask='{"color":"..."}' customizes the overlay color; type="primary" uses a primary-colored popup for emphasis; gap controls the highlight padding and radius (a number or {padding, radius}).

Non-modal + primary popup

Non-modal + primary popupCustom overlay color

Non-modal highlight 1

Non-modal highlight 2

Example

Keyboard navigation and indicators

keyboard (enabled by default) advances steps with ←/→; show-bullets renders clickable dot indicators; show-progress shows a top progress bar; progress-text is a template (placeholders current/total, each wrapped in double curly braces) for custom counter text; indicators="number" shows a numeric counter.

Keyboard + dots + progress bar

Start tour (keyboard + dots + progress)Disable keyboard navigation

Keyboard target 1

Keyboard target 2

Keyboard target 3

Example

Button visibility and pass-through props

hide-prev / hide-skip / hide-next / hide-counter control button/counter visibility; next-button-props / prev-button-props / skip-button-props pass arbitrary attributes to their buttons (JSON object). The last step's Finish is the next button (its label switches); on that step finish-button-props is layered on top of next-button-props (step-level wins).

Button visibility and props

Visibility + propsHide all actions

Button customization target 1

Button customization target 2

Example

Close button customization

show-close="false" hides the close button; close-icon replaces its content with arbitrary HTML.

Close button customization

Custom close iconNo close button

Close button target

Example

Overlay click and highlight interaction

mask-click-behavior: close (default) / next (advance on overlay click) / none (ignore); target-area-clickable makes the highlight area interactive (clicks pass through); disabled-interaction blocks interaction with the highlighted area; advance-on-click advances when the highlight area is clicked ("try it here" interactive tours).

Overlay click behavior + highlight interaction

Overlay click advancesOverlay click ignoredHighlight interactiveHighlight blockedClick highlight to advanceButton inside target not clicked yet

Highlight interaction target 1 Click me to verify interaction

Highlight interaction target 2

Example

Async steps

wait-for-element (ms) waits for the target to appear (e.g. "the previous step opened a dialog, wait for its inner element to render"); skip-missing-element skips the step when the target is missing / the wait times out.

Wait for async targets and skip

Wait for async targetSkip missing target

Delayed target (visible after 400ms)

Regular target

Example

Dialog mode

mode="dialog" (or step-level mode: "dialog") renders a centered dialog step without a target as a first-class step type.

Dialog mode

Start tour

Example

Lifecycle events

oas-highlight-start fires as soon as the step index changes (before any async target wait), while oas-highlight-end fires once the highlight has been positioned (positioning only happens after the async target wait resolves); oas-destroy fires when the tour closes (including external removal of open).

Lifecycle events

Start tourNo events yet

Lifecycle target 1

Lifecycle target 2

Example

Don't show again and multi-page tours

With dont-show-again, checking "Don't show this again" on close remembers the choice via storage-key; the next start is blocked and oas-dismiss fires. persist persists open/current state so a remount after route changes resumes the tour (multi-page tours).

Don't show again

Open tour (blocked once remembered)Clear memory

Memory target

Example

Multi-page tour (persist)

Start tourSimulate route change (remount)

Multi-page target 1

Multi-page target 2

Example

Typewriter and scroll lock

typewriter (opt-in, off unless set) + typewriter-speed reveal the description character by character; lock-scroll locks page scrolling during the tour; close-on-press-escape="false" disables Esc.

Typewriter animation + scroll lock

Start tour

Typewriter target 1 (with cover image)

Typewriter target 2

Example

Hints beacon mode

hints renders persistent pulsing beacons (no open needed); clicking a beacon opens a bubble. Hints with dismissable + id are remembered in localStorage (oas-tour-hint-${id}) and hidden afterwards.

Hints beacon mode

Beacon target 1 (dismissable)

Beacon target 2 (persistent)

Example

Mount point and z-index

append-to="body" (or a selector) mounts the whole overlay into the given container; z-index customizes the stacking level.

Mount point and z-index

append-to body + high z-index

Mount target

Example

Advanced customization (dual-axis gap / arrow aiming / no auto-reposition)

gap supports a dual-axis offset (number for all sides / [horizontal, vertical] array, orthogonal to padding); arrow-point-at-center keeps the arrow pointing at the target center after viewport avoidance shifts the popup; auto-reposition="false" disables overflow flipping and viewport avoidance (keeps the declared placement).

Dual-axis gap + arrow at center + no auto-reposition

Dual-axis gap offsetArrow at centerNo auto-reposition

Dual-axis gap target

Left-edge target

Bottom target (viewport edge)

Example

Custom indicators and actions (slots)

slot="indicators" replaces the built-in dots/number indicator (render with the current/total from the oas-step event); slot="actions" replaces the whole built-in button area with your own controls.

Custom indicators and actions

Start tour1 / 2

PreviousNext

Custom slot target 1

Custom slot target 2

Example

API

oas-tour

Attributes

Attribute	Description	Type	Default
advance-on-click	Click the highlighted area to advance to the next step (interactive tour)	boolean	—
append-to	Mount point: body or a CSS selector (moves the whole overlay into the target container)	string	—
arrow	Whether to show the arrow (boolean, default true; false hides)	string	true
arrow-point-at-center	Arrow points to the target center projection (stays accurate after viewport avoidance shifts the popup; by default the arrow sticks to the placement edge)	boolean	—
auto-reposition	Auto reposition on scroll/resize + overflow flip/viewport avoidance (default true; false keeps the declared placement without flipping or avoidance)	string	true
close-icon	Custom close button content (HTML string)	string	—
close-on-press-escape	Close on Esc (default true)	string	true
current	Current step index	string	0
disabled-interaction	Disable interaction on the highlighted area (interceptor covers target)	—	—
dont-show-again	Don't show again switch (boolean; if checked on close, remembered in localStorage)	boolean	—
finish-button-props	Pass-through props for the last-step Finish button (JSON): on the last step the next button is the Finish button, so finish-button-props is layered on top of next-button-props (step-level wins)	—	—
gap	Highlight padding: number (padding px) or {"padding","radius","offset"}; offset expands the highlight outward (number for all sides / [horizontal, vertical] dual-axis, orthogonal to padding); default padding 4	string	—
hide-counter	Hide the step counter	boolean	—
hide-next	Hide the next button	—	—
hide-prev	Hide the previous button	—	—
hide-skip	Hide the skip button	—	—
hints	Hints beacon mode: JSON [{id,selector,title,description,placement,dismissable}]; persistent pulsing beacons, click to open a bubble, dismissable is remembered after close	string	[]
indicators	Counter style: dots (default) / number / none	string	dots
keyboard	Keyboard ←/→ to advance steps (default true; false disables)	string	true
lock-scroll	Lock page scrolling during the tour (restored on close)	boolean	—
mask	Overlay switch/customization: false to disable (non-modal) or {"color","style"} to customize (default true); step-level override	string	true
mask-click-behavior	Overlay click behavior: close (default) / next (advance) / none (ignore)	string	close
mode	Popup mode: popup (default) / dialog (centered dialog without target); step-level override	string	popup
next-button-props	Props passed through to the next button (JSON object, e.g. {"data-x":"1"})	—	—
open	Start the tour (boolean attribute; starts when present)	boolean	—
persist	Multi-page tour: open/current state persisted to localStorage and restored on reconnect	boolean	—
placement	Popup placement: 12 directions (top/bottom/left/right × start/end/center) + center (centered when no target); default bottom; auto-flips when space is insufficient; step-level override	TourPlacement	bottom
prev-button-props	Props passed through to the previous button (JSON object)	—	—
progress-text	Progress text template: current/total placeholders each wrapped in double curly braces; when set, the counter area uses the template	string	—
scroll-into-view-options	scrollIntoView options for scrolling to the target (JSON; default {"behavior":"smooth","block":"center"})	string	—
scroll-padding	Padding when scrolling to the target (px; applied as target scroll-margin)	—	—
show-bullets	Dot indicators (click a dot to jump)	boolean	—
show-close	Show the close button (default true; false hides)	string	true
show-progress	Progress bar at the top of the popup (width advances with steps)	boolean	—
skip-button-props	Props passed through to the skip button (JSON object)	—	—
skip-missing-element	Skip the step when the target is missing / wait times out (default stays on the current step)	boolean	—
steps	Steps JSON (TourStep[] | string); property assignment supports function/element targets	TourStep[] | string	[]
storage-key	localStorage key (shared by dont-show-again / persist / hint dismiss)	string	oas-tour-dismiss
target-area-clickable	Highlight area is interactive (opt-in): off unless set (the interceptor covers the target so it is not clickable); when set the interceptor is hidden and clicks pass through to the target	string	—
type	Popup type: default / primary (primary-colored popup for non-modal emphasis)	string	default
typewriter	Typewriter animation (opt-in): off unless set; when set, the description is revealed character by character (typewriter="false" disables)	string	—
typewriter-speed	Typewriter speed (ms per character, default 20)	string	20
wait-for-element	Wait for the target to appear (ms, async steps; global default, step-level waitForElement wins)	—	—
z-index	Overlay z-index (default --oas-z-modal)	—	—

Events

Event	Description
oas-cancel	Skipped / Esc / overlay click, detail: { index, total, source } (source: skip/esc/close/mask)
oas-close	Close button clicked, detail: { index, total }
oas-destroy	Tour closed (including external removal of open), detail: { index, total }
oas-dismiss	Don't show again matched; tour start was blocked, detail: {}
oas-finish	Finish was clicked on the last step, detail: { index, total }
oas-highlight-end	Step highlight completed, detail: { index, total }
oas-highlight-start	Step highlight started (after async wait resolves), detail: { index, total }
oas-skip	Skip button clicked, detail: { index, total }
oas-step	Step changed, detail: { index, current, total, next, prev }

Slots

Name	Description
actions	Custom action area (replaces the whole built-in button area; hides the built-in prev/skip/next buttons when present)
cover	Step cover rich content (slot takes precedence over the step.cover image)
indicators	Custom indicator area (render with the oas-step current/total; hides the built-in dots/number indicator when present)

CSS Variables

CSS Variable	Default
--oas-glass-blur	none
--oas-glass-ring	transparent
--oas-tour-arrow-align-offset	16px
--oas-tour-arrow-height	12px
--oas-tour-arrow-radius	0
--oas-tour-arrow-width	12px
--oas-tour-mask-color	var(--oas-color-overlay)
--oas-tour-popup-bg	var(--oas-color-bg)

The overlay highlights the target, role="dialog" + aria-modal="true" (downgraded to aria-modal="false" in non-modal form when mask="false"); supports "Previous / Next / Skip", keyboard ←/→ and Esc.