Tracker

Tracker gives people a visual overview of a scrolling page or container. A track shows where content of interest appears, a viewport indicator shows the visible region, and markers help users navigate to relevant content. Ordered rules control what becomes a marker, how it looks, and how activation behaves; nearby markers can form clusters to keep the overview readable.

Where Tracker is useful

Use Tracker when the location of content matters as much as the content itself:

• Long documents, documentation, and readers: navigate sections and annotations without losing the overall structure. The long document recipe demonstrates a structured report.
• Extended forms: locate validation errors and completion states with the form recipe.
• Feeds and dashboards: find unresolved attention and critical events in the activity stream recipe.
• Review tools and editors: locate items needing attention along a scrollable surface, as in the audio caption review recipe.

Search matches, comments, and issues can also become markers when the application represents them as source elements matched by rules.

How Tracker works

Rules match source elements, Tracker measures their positions within a scrolling context, and the resulting markers show their relative locations on the track. The viewport indicator follows the visible region. Configurable interaction can scroll to or focus relevant content, while automatic updates and explicit synchronization keep the overview aligned with changing content.

The source root selects what to search; the scroll root selects the scrolling context. An integration also has a rendering host/root that determines where its output lives. The package documentation explains who owns that output and how to place it.

Choose a package

Choose the adapter that matches your application's integration model. Use Core when building your own Tracker integration or rendering adapter.

Choose Vanilla when your code should explicitly create and mount an instance; choose Element when a Custom Element's DOM lifecycle should manage the integration. Element options and rules use JavaScript configuration, not HTML configuration attributes. The framework packages have no standalone browser bundles; exact entry points and debug setup remain package-specific.

The Vanilla and Element standalone builds are also available directly from a CDN; see the CDN guide.

Each official adapter README is self-contained for the API exposed by that package, including options, rules, lifecycle, events, styling, and environment restrictions. Start with the adapter you install. Core documentation primarily serves custom integration authors.

Quick-start orientation

Install @rightxt/tracker-vanilla with your package manager. With a bundler that supports CSS imports, run this after the document body and headings exist:

import Tracker from '@rightxt/tracker-vanilla';
import '@rightxt/tracker-vanilla/style.css';

const tracker = new Tracker({
  options: { a11y: { enabled: true, keyboard: true } },
  rules: [{ selector: 'h2', label: (element) => element.textContent }],
});
tracker.mount();

const disposeTracker = () => tracker.destroy();

Call disposeTracker() when the owning view is removed. This example uses page tracking. In Vanilla, an omitted renderHost resolves to the inferred mount/request document's body; explicit source/scroll identities can establish a same-origin child-document request context. See the Vanilla quick start for the complete package setup.

Package-specific starts: Core, Vanilla, Element, React, Vue, and Angular.

Options cover presentation, clustering, updates, interaction, accessibility, and diagnostics. Ordered rules choose and present markers. Configuration and lifecycle details belong to the package you use.

Environments at a glance

Tracker supports these environment categories. Exact setup and restrictions depend on the adapter and its rendering model. The renderer target/render root determines the active DOM realm; source and scroll roots must be compatible with it.

Document replacement or navigation requires the package's appropriate remount/recreation lifecycle. Use the environment guide and your package's environment section for the actual setup.

Demos and Theme Builder

The example links below open repository source documentation.

• Recipes show application workflows using the production Tracker profile. Start with the document, form, activity stream, and audio review recipes under Where Tracker is useful.
• Scenarios isolate a behavior or environment. Explore styling, clustering, observation, rule resolution, accessibility, or diagnostics.
• Playgrounds provide package-oriented interactive experimentation: Vanilla, Element, React, Vue, and Angular.

Theme Builder is an interactive helper for Tracker's public styling contract, with theme preview and application override export. Load your package's stylesheet and use the styling reference for the supported customization surface.

Documentation

Packages

For installation and normal adapter use, the package README is the primary API reference: Vanilla, Element, React, Vue, or Angular.

For a custom integration, begin with Core, then follow the custom integration guide and the Core references below.

Guides

Reference

The styling reference applies broadly across packages. The three Core references primarily serve Core/custom integration authors; adapter users can rely on their package README and follow these references when supplementary detail is useful.