Guided Tour — ARC UI

Components

Guided Tour

feedback

interactive

<arc-guided-tour>

Overview

Guidelines

When to use

Keep tours short — 3 to 5 steps is ideal for onboarding
Write concise step titles and descriptions that explain why, not just what
Always provide a Skip option so users are not trapped in the tour
Persist tour completion state so returning users are not shown the tour again
Target elements that are already rendered — avoid spotlighting lazy-loaded content

When not to use

Create tours with more than 7 steps — break them into multiple focused tours
Use guided-tour for error messages or alerts — it is for onboarding and discovery
Target elements inside scrollable containers without ensuring they are visible
Trigger the tour automatically on every page load — use a first-visit or feature-flag check
Rely on the tour as the only form of documentation — it supplements, not replaces, help content

Features

Declarative step definitions with target selector, title, and content
Spotlight overlay dims the page while highlighting each target element
Popover-styled tooltips auto-positioned next to the highlighted element
Built-in navigation: Back, Next, Skip, and Finish buttons
Step counter with accent-primary gradient text for progress indication
Automatic scroll-into-view for off-screen target elements
arc-change, arc-complete, and arc-dismiss events for state tracking
Keyboard navigation — Arrow keys to advance/go back, Escape to dismiss
Respects prefers-reduced-motion for overlay transitions
Composable — uses spotlight and popover internally

Preview

Start Tour

Usage

This component requires JavaScript. No pure HTML/CSS version is available — use the Web Component directly or a framework wrapper.

<script type="module" src="@arclux/arc-ui"></script>

<arc-guided-tour id="tour"></arc-guided-tour>

<arc-button id="start-tour" variant="primary">Start Tour</arc-button>
<div id="step-1">Feature One</div>
<div id="step-2">Feature Two</div>

<script>
  const tour = document.getElementById('tour');
  tour.steps = [
    { target: '#step-1', title: 'Feature One', content: 'This is the first feature.' },
    { target: '#step-2', title: 'Feature Two', content: 'This is the second feature.' },
  ];
  document.getElementById('start-tour').addEventListener('click', () => {
    tour.open = true;
  });
</script>

import { GuidedTour, Button } from '@arclux/arc-ui-react';
import { useRef, useState } from 'react';

const steps = [
  { target: '#step-1', title: 'Feature One', content: 'This is the first feature.' },
  { target: '#step-2', title: 'Feature Two', content: 'This is the second feature.' },
];

export function TourDemo() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <GuidedTour steps={steps} open={open}
        onArcComplete={() => setOpen(false)}
        onArcDismiss={() => setOpen(false)} />
      <Button variant="primary" onClick={() => setOpen(true)}>Start Tour</Button>
      <div id="step-1">Feature One</div>
      <div id="step-2">Feature Two</div>
    </>
  );
}

<script setup>
import { ref } from 'vue';
import { Button, GuidedTour } from '@arclux/arc-ui-vue';

const open = ref(false);
const steps = [
  { target: '#step-1', title: 'Feature One', content: 'This is the first feature.' },
  { target: '#step-2', title: 'Feature Two', content: 'This is the second feature.' },
];
</script>

<template>
  <GuidedTour :steps="steps" :open="open"
    @arc-complete="open = false" @arc-dismiss="open = false" />
  <Button variant="primary" @click="open = true">Start Tour</Button>
  <div id="step-1">Feature One</div>
  <div id="step-2">Feature Two</div>
</template>

<script>
  import { Button, GuidedTour } from '@arclux/arc-ui-svelte';

  let open = false;
  const steps = [
    { target: '#step-1', title: 'Feature One', content: 'This is the first feature.' },
    { target: '#step-2', title: 'Feature Two', content: 'This is the second feature.' },
  ];
</script>

<GuidedTour {steps} {open}
  on:arc-complete={() => open = false}
  on:arc-dismiss={() => open = false} />
<Button variant="primary" on:click={() => open = true}>Start Tour</Button>
<div id="step-1">Feature One</div>
<div id="step-2">Feature Two</div>

import { Component } from '@angular/core';
import { Button, GuidedTour } from '@arclux/arc-ui-angular';

@Component({
  imports: [Button, GuidedTour],
  template: `
    <GuidedTour [steps]="steps" [open]="open"
      (arc-complete)="open = false" (arc-dismiss)="open = false"></GuidedTour>
    <Button variant="primary" (click)="open = true">Start Tour</Button>
    <div id="step-1">Feature One</div>
    <div id="step-2">Feature Two</div>
  `,
})
export class TourDemoComponent {
  open = false;
  steps = [
    { target: '#step-1', title: 'Feature One', content: 'This is the first feature.' },
    { target: '#step-2', title: 'Feature Two', content: 'This is the second feature.' },
  ];
}

import { Button, GuidedTour } from '@arclux/arc-ui-solid';
import { createSignal } from 'solid-js';

const steps = [
  { target: '#step-1', title: 'Feature One', content: 'This is the first feature.' },
  { target: '#step-2', title: 'Feature Two', content: 'This is the second feature.' },
];

export function TourDemo() {
  const [open, setOpen] = createSignal(false);

  return (
    <>
      <GuidedTour steps={steps} open={open()}
        onArcComplete={() => setOpen(false)}
        onArcDismiss={() => setOpen(false)} />
      <Button variant="primary" onClick={() => setOpen(true)}>Start Tour</Button>
      <div id="step-1">Feature One</div>
      <div id="step-2">Feature Two</div>
    </>
  );
}

import { Button, GuidedTour } from '@arclux/arc-ui-preact';
import { useState } from 'preact/hooks';

const steps = [
  { target: '#step-1', title: 'Feature One', content: 'This is the first feature.' },
  { target: '#step-2', title: 'Feature Two', content: 'This is the second feature.' },
];

export function TourDemo() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <GuidedTour steps={steps} open={open}
        onArcComplete={() => setOpen(false)}
        onArcDismiss={() => setOpen(false)} />
      <Button variant="primary" onClick={() => setOpen(true)}>Start Tour</Button>
      <div id="step-1">Feature One</div>
      <div id="step-2">Feature Two</div>
    </>
  );
}

API

Prop	Type	Default	Description
`steps`	`Array<{ target: string; title: string; content: string }>`	`[]`	Array of step definitions. Each step specifies a CSS selector for the target element, a title for the popover heading, and content for the popover body.
`active`	`number`	—	Read-only property reflecting the zero-based index of the currently active step.
`open`	`boolean`	`false`	Controls whether the tour is active. Set to true to start the tour from the first step.

Events

Event	Description
`arc-change`	Fired when the tour advances or goes back to a different step. Detail contains { step } with the new step index.
`arc-complete`	Fired when the user finishes the last step of the tour
`arc-dismiss`	Fired when the user skips or closes the tour before completing all steps

Overview

Guidelines

When to use

When not to use

Features

Preview

Usage

API

Events

See Also

ARC UI

Arclight