@qocial/tour - npm
npm
Search<br>Sign UpSign In
@qocial/tour
1.0.0 • Public • Published a day ago<br>Readme<br>Code Beta<br>0 Dependencies<br>0 Dependents<br>1 Versions<br>@qocial/tour
Lightweight, zero-dependency page tour and user onboarding SDK for any website or web app. Drop in two files, define steps externally, and your interactive walkthrough is live.
Features
Zero dependencies - no jQuery, no React, no runtime bloat
Framework agnostic - works with Vanilla JS, React, Vue, Angular, Svelte, or any stack
CDN or npm - one tag or a standard ES module import
External step configuration - define tour steps in a separate JSON file or JS array; no SDK rebuild needed
TypeScript support - ships with full type declarations (QocialTourStep, QocialTourOptions)
Responsive & mobile-first - anchored card on desktop, bottom sheet on mobile (<br>Rich HTML descriptions - embed images, YouTube videos, or any HTML inside step tooltips
Theming via CSS variables - override colors, radius, and card width without touching source
Full lifecycle callbacks - onStart, onStep, onComplete, onSkip, onStop
Overlay & spotlight - highlights the target element with a configurable overlay
Auto placement - tooltip card flips automatically to stay inside the viewport
Accessible - 44px touch targets, focus management, and keyboard navigation support
Table of Contents
Install
Step Configuration
API
HTML Descriptions
Responsive & Mobile Support
Theming
TypeScript
Naming Convention
Works With
Local Development
License
Install
CDN (no build step required)
link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@qocial/tour/dist/qocial-tour.min.css"><br>script src="https://cdn.jsdelivr.net/npm/@qocial/tour/dist/qocial-tour.min.js">script><br>script src="/tours/my-app-tour.js">script><br>script><br>// init() returns a Promise - handle errors with .catch()<br>QocialTour.init({ steps: window.MyAppTour, autoStart: true }).catch(console.error);<br>script>
npm
npm install @qocial/tour
import QocialTour from "@qocial/tour";<br>import "@qocial/tour/css";<br>import steps from "./my-app-tour.json";
QocialTour.init({ steps, autoStart: true });
Step Configuration
Each step is an object in an array. Steps can be defined inline, loaded from a local JS file, or fetched from a remote JSON URL.
Field<br>Required<br>Description
step<br>No<br>Step number (defaults to array index + 1)
target<br>Yes<br>CSS selector, or parent:#selector shorthand
useParent<br>No<br>Highlight the parent element of target
title<br>Yes<br>Plain text title shown in the tooltip card
description<br>No<br>Plain text or HTML (images, YouTube embeds, etc.)
placement<br>No
auto, top, bottom, left, right
window.MyAppTour = [<br>step: 1,<br>target: "#profile",<br>useParent: true,<br>title: "Your profile",<br>description: "Manage your account here."<br>},<br>step: 2,<br>target: "#help",<br>title: "Video walkthrough",<br>description: `<br>Watch this quick demo:
];
Load steps from a remote JSON URL (async fetch):
// init() is async when steps is a URL - always await it<br>await QocialTour.init({ steps: "/tours/my-app-tour.json", autoStart: true });
API
// Always await init() - it may fetch a JSON file<br>await QocialTour.init({<br>steps: [...], // array or JSON URL string<br>autoStart: false,<br>showProgress: true,<br>overlay: true,<br>zIndex: 9999,<br>labels: { next: "Next", prev: "Back", skip: "Skip", finish: "Done" },<br>onStart({ total }) {},<br>onStep({ step, index, total, skipped, reason }) {},<br>onComplete() {},<br>onSkip() {},<br>onStop() {}, // called when stop() is invoked programmatically<br>});
// Pass the trigger element so focus returns to it when the tour closes<br>const btn = document.getElementById("start-tour");<br>btn.addEventListener("click", function () {<br>QocialTour.start(this);<br>});
QocialTour.next();<br>QocialTour.prev();<br>QocialTour.stop(); // silent stop, fires onStop<br>QocialTour.skip(); // fires onSkip<br>QocialTour.destroy(); // remove all DOM + event listeners<br>QocialTour.getState(); // { active, currentIndex, totalSteps, currentStep }
HTML Descriptions
The description field renders as HTML. All tour configs are developer-authored, so content is treated as trusted - the same as writing HTML directly in your page.
Use .qocial-tour-media.qocial-tour-media--video for responsive 16:9 YouTube embeds:
div class="qocial-tour-media qocial-tour-media--video"><br>iframe src="https://www.youtube.com/embed/VIDEO_ID"<br>title="Demo" frameborder="0" allowfullscreen>iframe><br>div>
Note for CMS / user-supplied content: If descriptions come from a database, CMS, or user input, sanitize them with DOMPurify before passing to init():
import DOMPurify from "dompurify";<br>const steps = rawSteps.map(s => ({ ...s, description: DOMPurify.sanitize(s.description) }));<br>await QocialTour.init({ steps });
Responsive & Mobile Support
Desktop (≥ 640px): tooltip card anchors near the highlighted element and flips automatically to stay in the viewport.
Mobile (Long HTML content scrolls inside .qocial-tour-description.
Theming
Override CSS variables on your site - no SDK changes needed:
:root {<br>--qocial-tour-overlay:...