Skip to content
awesome-tour

Type to search every page.

    EUtilitiesContents

    Utilities

    Anchors, DOM helpers, stores and target resolution exported by the core for custom integrations.

    Lower-level building blocks used by the React package. Useful when integrating another framework, a canvas renderer or custom UI.

    Anchors

    Anchors let components register themselves as targets under a stable name, so tours don’t depend on CSS selectors.

    import { anchor, defaultAnchors } from '@awesome-tour/core';
    const unregister = defaultAnchors.register('create-button', buttonElement);
    // step: { id: 'create', target: anchor('create-button') }
    unregister();
    Export Signature Description
    anchor(id) (id: string) => AnchorTarget Reference a registered anchor as a step target.
    isAnchorTarget(value) (value: unknown) => value is AnchorTarget Type guard.
    createAnchorRegistry() () => AnchorRegistry A new, isolated registry (pass it to createTour({ anchors }) and TourProvider anchors).
    defaultAnchors AnchorRegistry Process-wide registry used when none is given.

    AnchorRegistry

    Method Description
    register(id, node) Register an element or virtual element under id; returns an unregister function. Several nodes per id are allowed (highlighted together).
    get(id) Registered nodes for id.
    subscribe(listener) Called on every register/unregister — tours waiting for an anchor resolve as soon as it registers.

    In React use useTourAnchor(id) or <Tour.Anchor>; in react-three-fiber, <TourTarget3D name> registers a virtual element.

    Targets

    Export Description
    resolveTarget(input, anchors) Synchronously resolve a TargetInput into nodes. Disconnected elements are dropped; returns [] during SSR.
    waitForTarget(input, { anchors, timeout, signal? }) Resolve, waiting up to timeout ms for the target to appear (DOM mutations, anchor registrations, 100 ms polling). Resolves [] on timeout; rejects with an AbortError when signal aborts. Arrays resolve as soon as every item is present, or with whatever was found at timeout.
    deepQuerySelectorAll(selector, root?) querySelectorAll that searches every open shadow root (nested ones too) when the light DOM has no match.
    byTour(name, { within? }) Target: elements with data-tour="name".
    byRole(role, { name?, exact?, within? }) Target: elements with this ARIA role (explicit or implicit) and accessible name (substring, exact, or RegExp).
    byText(text, { exact?, selector?, within? }) Target: the innermost elements whose text matches.
    firstOf(...targets) Target: the first candidate that resolves (a fallback chain).
    accessibleName(element) The simplified accessible name byRole matches against.
    subscribeDomActivity(listener) / subscribeTicker(ms, listener) The shared observer behind every watcher: DOM mutations (and open shadow roots), input/change, or a shared interval. Return an unsubscribe.
    getObserverStats() Live hub subscribers — for leak tests.

    Campaigns

    Export Description
    createExperiment(options) A/B test tours: stable assignment, control groups, variant on analytics events. See Experiments.
    createFeed(options) A “what’s new” feed with read/unread state (useFeed in React). See Help center.
    previewFromUrl(manager, { load }) Run the draft named in ?tour-preview= as a preview tour. Returns a cleanup that restores the published one.
    localize(value, locale, fallback?) / isLocalized(value) Pick the text for a locale from { en, pt, … }. useLocalize() in React.
    deepLink(manager, options?) Start the tour named in the URL. TourProvider’s deepLink prop wraps it.

    Geometry

    Export Description
    observeRect(targets, onChange, options?) Calls onChange with the union rect whenever it changes (resize, any scroll, window resize, DOM mutations). With { animationFrame: true } it polls every frame instead — the default when a target is a virtual element. Returns a cleanup.
    getRect(node) Viewport RectLike of an element or virtual element.
    getTargetsRect(targets) Union rect of several nodes, or null.
    unionRects(rects) Bounding box of rects, or null for an empty list.
    inflateRect(rect, padding) Grow a rect by a number or { top, right, bottom, left }.
    rectsEqual(a, b) Compare position and size.
    toRect(x, y, width, height) Build a RectLike.
    createVirtualTarget(targets) Wrap targets as one virtual element whose rect is their union (for positioning libraries). null for an empty list.
    isElement(value) / isVirtualElement(value) Type guards.
    import { inflateRect, observeRect } from '@awesome-tour/core';
    const stop = observeRect(tour.getState().targets, (rect) => {
    if (!rect) return;
    const r = inflateRect(rect, 8);
    highlight.style.transform = `translate(${r.x}px, ${r.y}px)`;
    highlight.style.width = `${r.width}px`;
    highlight.style.height = `${r.height}px`;
    });

    Scrolling

    Export Description
    scrollTargetsIntoView(targets, options?, maxWait?) If the targets aren’t fully visible (8px margin), scrolls the first element into view (block: 'center', smooth unless reduced motion; options override) — nested scroll containers included — then resolves when the layout is stable. maxWait defaults to 800 ms.
    waitForStableRect(targets, maxWait?) Resolves after two identical animation frames, or maxWait ms (default 800).
    lockScroll() Locks page scroll (overflow: hidden, compensating the scrollbar width). Ref-counted; returns a release function.

    Modality

    Export Description
    inertOthers(keep) Make everything outside the keep elements inert (non-focusable, hidden from assistive tech). Skips aria-live regions, elements with data-tour-keep, and elements the app already made inert. Ref-counted; returns a restore function.
    KEEP_ATTRIBUTE 'data-tour-keep'. Elements with it (and their subtrees) are never made inert, and tour keyboard shortcuts ignore events from them.
    isFromKeptElement(event) Whether an event originated inside a data-tour-keep subtree (shadow DOM aware).
    prefersReducedMotion() matchMedia('(prefers-reduced-motion: reduce)'), false on the server.
    isBrowser true when window and document exist.
    <!-- Stays usable while a modal tour is open -->
    <div id="toasts" data-tour-keep></div>

    Stores and events

    The primitives behind tours, checklists and the manager — reuse them for your own state that needs to work with useStoreSelector.

    import { createEmitter, createStore } from '@awesome-tour/core';
    const store = createStore({ count: 0 });
    store.subscribe(() => console.log(store.getState().count));
    store.setState((s) => ({ count: s.count + 1 }));
    const emitter = createEmitter<{ saved: { id: string } }>();
    const off = emitter.on('saved', ({ id }) => console.log(id));
    emitter.emit('saved', { id: '1' });
    Export Description
    createStore(initial) { getState, setState, subscribe }. setState takes a partial object or (state) => partial, shallow-merges into a new snapshot, and only notifies when a value changed (Object.is).
    createEmitter(onError?) Typed { on, emit, clear }. on returns an unsubscribe function. Handler errors go to onError when given, otherwise they are rethrown.