API reference

Every export.

@cairnkit/core

Framework-free engine. Zero runtime dependencies.

PropTypeDefaultDescription
defineAnchors(registry)<T>(T) => T—Declares the anchor registry. Identity at runtime; exists for type inference.
anchor(id)(id) => props—Props object to spread onto an element.
anchorSelector(id)(id) => string—The CSS selector for an anchor, escaped.
resolveAnchor(id, doc?)(id) => HTMLElement | null—Finds the visible element for an anchor. Returns null on the server.
defineFlow(flow)(TourFlow) => TourFlow—Declares a flow.
createFlowRegistry(flows)(TourFlow[]) => Registry—Builds an id → flow map.
getFlow(registry, id)(...) => TourFlow | null—Looks a flow up by id.
resolveResumeStep(flow, path, i)(...) => number | null—Where to resume when the user is ahead. Pure, testable.
decideForRoute(flow, path, i)(...) => RouteDecision—handoff / pause / resume / none, in that order.
createTourStore(options)(...) => TourStore—Observable store, useSyncExternalStore-ready.
createActionRegistry()() => ActionRegistry—Backs ctx.run in step hooks. One per provider — never module-level, which would leak across SSR requests.
localStoragePersist(key?)(key?) => PersistAdapter—Default persistence. Progress must survive a page transition.
emitTourEvent(name)(name) => void—Signal from your app that a step is waiting on.
onTourEvent(name, fn)(...) => () => void—Subscribe. Returns an unsubscribe.
readRect / rectsEqualhelpers—Measure and compare a target rect.
watchForAnchor(id, ms, cb)(...) => () => void—Wait for a late-mounting anchor.
scrollAnchorIntoView(el)(el) => void—Reduced-motion aware.

Key types

TourFlow · TourStep · AdvanceRule · Placement · AnchorId
CairnRegister · RegisteredAnchor · RegisteredFlowId · RegisteredEvent · RegisteredAction
StepContext · ActionRegistry · TourAction
CairnEvent · CairnEventHandler · TargetRect · TourStore · PersistAdapter
TourDismissReason · TourExitReason

Events

One onEvent callback receives every signal a tour emits. Point it at your analytics, or at @cairnkit/cloud.

PropTypeDefaultDescription
flow_startedflowId, version—A tour began.
step_viewedflowId, stepIndex, anchor—One per step, however many times it re-renders.
flow_completedflowId, version—Reached the end.
flow_dismissedflowId, version, stepIndex, reason—Left early. reason is 'skipped' (the Skip button), 'closed' (the X) or 'escape'. Three different intents kept apart because they argue for opposite fixes: a step people skip is unwanted, a step people close is usually one whose card covers what they were trying to see.
flow_handofffromFlowId, toFlowId, pathname—One tour handed off to another.
anchor_missingflowId, stepIndex, anchor, pathname, optional?—A step pointed at UI that was not on the page — what cairnkit check catches before release, seen from production. `optional: true` is set when the step declared itself optional, so an expected absence can be told from a break: count these as breakage and a guide skipping a step exactly as intended reads as a broken anchor. Absent, never false, on a required step.
step_feedbackflowId, stepIndex, clear, note—A reader said whether the step made sense.

Every event is { name, props }, so the callback maps onto an analytics client directly. Nothing below needs an account with us.

app/providers.tsx
<CairnProvider
  flows={flows}
  onEvent={(event) => posthog.capture(event.name, event.props)}
>
  {children}
</CairnProvider>

Segment, Amplitude, Mixpanel and a plain fetch to your own collector take the same shape. To send to a tool and to cloud, call both:

app/providers.tsx
import { sendToCloud } from "@cairnkit/cloud";

// Calls sharing a key share one transport, so an inline call during render is
// also correct. Named here only because it is used alongside another handler.
const toCloud = sendToCloud({ key: process.env.NEXT_PUBLIC_CAIRNKIT_KEY! });

<CairnProvider
  flows={flows}
  onEvent={(event) => {
    posthog.capture(event.name, event.props);
    toCloud(event);
  }}
>

@cairnkit/react

Headless bindings. No styling.

PropTypeDefaultDescription
<CairnProvider>component—Mounts the runtime. Props: flows, router, translate, onEvent, onNotice, store, mobileBreakpoint.
useTour()hook—The controller: flow, step, rect, element, status, advance, back, skip, start, stop. Mount it once: it binds listeners and fires lifecycle hooks.
useActiveTour()hook—Read-only view: flow, stepIndex, pathname, decision, isPaused. No side effects, so it is safe beside useTour.
useStartTour()hook—Just the starter, without the driver. What a custom launcher wants.
useTourScope(scope)hook—Declares which tab or stage is in front, for flows that carry a scope.
useTourState(selector)hook—Subscribe to a slice of store state.
useStepCopy(flow, step)hook—Resolves title and body, inline or via translate.
useTourDeepLink(param?)hook—Starts a flow from ?tour=. Each value honoured once.
useCairn()hook—Raw context: flows, router, store.
useTourAction(name, fn)hook—Publishes an action a step can call via ctx.run, for as long as the component is mounted.
useAnchorTarget(id, opts)hook—Resolves one anchor to a live element and rect, and reports status while it waits. What useTour drives internally; useful when building your own overlay. Options: waitForMs, enabled, resetKey.
memoryRouteradapter—For an app with no router, and the default in tests. Reads window.location.pathname and navigates with window.location.assign. Prefer it over hand-writing an adapter that returns a fixed path.
<TourAnchor id>component—Escape hatch for components that swallow props.

Also re-exports defineFlow, defineAnchors, anchor and the flow types from @cairnkit/core, so authoring a tour needs one import rather than two. Note that augmenting CairnRegister still has to target @cairnkit/core — an interface cannot be merged through a re-export — which is why core is a direct dependency in the install command.

@cairnkit/ui

Prebuilt overlay. Plain prefixed CSS, light and dark.

PropTypeDefaultDescription
<CairnOverlay>component—Spotlight plus tooltip card. Props: labels, mobileBreakpoint, onNotice.
<TourLauncher>component—The launcher. Props: flowId, label, position, pulse, icon, className.
<Spotlight>component—Scrim and cutout only.
<StepCard>component—The card only.
<Launcher>component—Presentational launcher, unbound to a flow.
<ProgressRail>component—Segmented step progress.
<CairnNoticeBar>component—Renders the notices the provider raises, such as an anchor that never appeared. Props: labels.
<Button>component—The card's own button, exported so a custom card can match it.
<IconButton>component—Icon-only variant, used for dismiss.
@cairnkit/ui/styles.cssstylesheet—Import once. Required for the prebuilt components.

@cairnkit/next

PropTypeDefaultDescription
useAppRouterAdapter()hook—App Router adapter.
usePagesRouterAdapter()hook—Pages Router adapter. Reads router.asPath, not router.pathname, so it reports the resolved path rather than the route pattern.
appRouterAdapter()function—Non-hook form, kept for callers that cannot use a hook. Prefer useAppRouterAdapter: this one calls useRouter inside navigate, which breaks the rules of hooks.

@cairnkit/cloud

Optional. Reports the events the library already emits to cairnkit cloud. Nothing else in the library depends on it.

PropTypeDefaultDescription
sendToCloud(opts)function—Returns an onEvent handler for CairnProvider. Options: key, and optionally endpoint. Batches and sends with sendBeacon.
reportFlows(opts)function—Sends the flow and step copy once per locale, so the dashboard can name a step instead of numbering it. Deduped on a fingerprint of the content, so a locale switch reports again. Options: key, flows, locale.
currentSession()function—The current session id, from localStorage, rotating after an idle gap. Exported because a custom transport needs the same id the built-in one uses.

@cairnkit/cli

PropTypeDefaultDescription
cairnkit check <dir>command—Static drift check. Exits 1 on any finding.
cairnkit status <dir>command—Describe every anchor: whether an element carries it, how it was applied, where it was declared, and which flows point at it. Always exits 0 — describing is not judging.
--jsonflag—On check or status. Writes exactly one JSON object to stdout and every human-facing message to stderr, so the output pipes straight into a parser. The payload carries a version field.
auditFlow(page, opts)function—Drives one flow in a browser and reports per-step.
auditFlows(page, list)function—Several flows; throws one readable error if any fail.