Skip to content

README.md

Latest commit

 

History

History
168 lines (137 loc) · 4.86 KB

README.md

File metadata and controls

168 lines (137 loc) · 4.86 KB

@pantarey.io/ngx-guided-tour-lite

A lightweight, dependency-free guided tour library for Angular — made for onboarding flows and feature tours.

Used in production at pantarey.io.

  • Zero dependencies — only @angular/core as peer dependency
  • JSON-driven tours — define tours as JSON objects or pass a JSON string directly; store tours in a database, load them from an API, or keep them in static files
  • Embedded CSS — works out of the box, no extra stylesheets to import
  • Fully themeable — 12 CSS custom properties to match any brand
  • Mobile-ready — responsive positioning with separate mobileSteps for small screens
  • Multi-language — built-in locale resolution with per-step translations
  • Smart positioning — auto-repositions when elements move or resize (e.g. accordion, animation)
  • Interactive steps — gate steps (wait for click → wait for target), typewriter fill, pause & resume
  • Glass-morphism design — dark, modern popover with blur, gradients, and smooth transitions

Installation

npm install @pantarey.io/ngx-guided-tour-lite

Quick Start

import { GuidedTourService } from '@pantarey.io/ngx-guided-tour-lite';

@Component({ ... })
export class MyComponent {
  private tour = inject(GuidedTourService);

  startTour() {
    this.tour.startTour({
      options: {
        overlayOpacity: 0.6,
        showProgress: true,
      },
      steps: [
        {
          selector: '#step-1',
          side: 'bottom',
          text: {
            en: { title: 'Welcome', description: 'This is the first step.' },
            de: { title: 'Willkommen', description: 'Das ist der erste Schritt.' },
          },
        },
        {
          selector: '#step-2',
          side: 'right',
          text: {
            en: { title: 'Next Feature', description: 'Here is another feature.' },
          },
        },
      ],
      onComplete: () => console.log('Tour finished!'),
    });
  }
}

API

GuidedTourService

Provided in root — just inject it.

Method Description
startTour(config) Start a tour. Accepts GuidedTourConfig object or JSON string.
destroy() Stop the tour and clean up.
active Signal<boolean> — whether a tour is currently running.

GuidedTourConfig

interface GuidedTourConfig {
  options?: {
    overlayOpacity?: number;   // Default: 0.6
    allowClose?: boolean;      // Default: true (Escape + click outside)
    showProgress?: boolean;    // Default: false ("1 / 5" counter)
    stagePadding?: number;     // Default: 12
    stageRadius?: number;      // Default: 10
    locale?: string;           // Default: navigator.language
    labels?: GuidedTourLabels; // Default: English
  };
  steps: GuidedTourStep[];
  mobileSteps?: GuidedTourStep[];  // Used when viewport ≤ 600px
  onComplete?: () => void;
}

GuidedTourStep

interface GuidedTourStep {
  selector: string;
  side?: 'top' | 'bottom' | 'left' | 'right';
  align?: 'start' | 'center' | 'end';
  action?: 'info' | 'gate' | 'pauseAndResume' | 'destroyOnClick' | 'typewriterFill';
  text?: Partial<Record<string, GuidedTourText>>;
  showPopover?: boolean;
  // ... see source for full type
}

Step Actions

Action Behavior
info (default) Normal step with Next/Back buttons
gate Waits for user to click the highlighted element, then waits for gateSelector to appear before advancing
pauseAndResume Pauses tour on click, polls for resumeSelector, then resumes remaining steps
destroyOnClick Ends the tour when user clicks the highlighted element
typewriterFill Types text into form fields char-by-char, then auto-advances

Labels

Override button text for any language:

{
  options: {
    labels: {
      prev: 'Zurück',
      next: 'Weiter',
      done: 'Fertig',
      close: 'Schließen',
    },
  },
}

Theming

Override CSS custom properties to match your brand:

:root {
  --guided-tour-primary: #3b82f6;        /* Accent color */
  --guided-tour-bg: #1a1a2e;             /* Popover background */
  --guided-tour-text: #fff;              /* Primary text */
  --guided-tour-text-secondary: rgba(255,255,255,.78);
  --guided-tour-text-muted: rgba(255,255,255,.35);
  --guided-tour-border: rgba(255,255,255,.1);
  --guided-tour-divider: rgba(255,255,255,.06);
  --guided-tour-arrow-bg: #1a1a2e;
  --guided-tour-z-index: 10000;
  --guided-tour-max-width: 400px;
  --guided-tour-radius: 16px;
  --guided-tour-font: inherit;
}

Compatibility

  • Angular 19+ (uses signal from @angular/core)
  • Works with standalone components and NgModules
  • No zone.js dependency

Used by

pantarey.io — Digital workspace for process automation, data management, and AI

License

MIT — Pantarey GmbH
⚡