Skip to main content
userTourKit
@tour-kit/reactHeadless

Headless Components

Headless tour components: unstyled primitives with render props for building completely custom tour interfaces

domidex01Published

Headless components provide all the tour logic without any styling, giving you complete control over the UI.

Import

import {
  HeadlessTourCard,
  HeadlessTourOverlay,
  HeadlessTourNavigation,
  HeadlessTourProgress,
} from '@tour-kit/react/headless';

Headless components use render props to expose state and actions, letting you build completely custom UIs.

Why Headless?

  • Full Design Control - No default styles to override
  • Framework Agnostic Styling - Use any CSS approach
  • Smaller Bundle - Only includes logic, not styles
  • Design System Integration - Match your existing components

Basic Example

import { HeadlessTourCard } from '@tour-kit/react/headless';

function MyTourCard() {
  return (
    <HeadlessTourCard>
      {({ currentStep, currentStepIndex, totalSteps, next, prev, skip }) => (
        <div className="my-card">
          <span>{currentStepIndex + 1} / {totalSteps}</span>
          <h3>{currentStep?.title}</h3>
          <p>{currentStep?.content}</p>
          <div>
            <button onClick={prev}>Back</button>
            <button onClick={next}>Next</button>
            <button onClick={skip}>Skip</button>
          </div>
        </div>
      )}
    </HeadlessTourCard>
  );
}

Available Headless Components

ComponentDescription
HeadlessTourCardTour card container with step data
HeadlessTourOverlaySpotlight overlay with position data
HeadlessTourNavigationNavigation controls
HeadlessTourProgressProgress indicator data

Hooks for Full Control

For maximum flexibility, use hooks directly:

import { useTour, useStep, useSpotlight } from '@tour-kit/core';

function CompletelyCustomTour() {
  const tour = useTour('my-tour');
  const step = useStep();
  const spotlight = useSpotlight();

  // Build your entire UI from scratch
  return (
    <>
      {spotlight.isVisible && <MyCustomOverlay rect={spotlight.targetRect} />}
      {tour.isActive && <MyCustomCard step={step} tour={tour} />}
    </>
  );
}

Combining with Styled Components

Mix headless and styled components:

import { Tour, TourStep, TourOverlay } from '@tour-kit/react';
import { HeadlessTourCard } from '@tour-kit/react/headless';

<Tour id="mixed">
  <TourStep target="#btn" title="Hello" content="World" />

  {/* Use styled overlay */}
  <TourOverlay />

  {/* Use headless card with custom UI */}
  <HeadlessTourCard>
    {(props) => <MyCustomCard {...props} />}
  </HeadlessTourCard>
</Tour>
Free & open source

Ship onboarding, not config.

npm i @tour-kit/core is MIT and free. The Pro packages work unlicensed too — a one-time $99 license removes the production watermark when you ship.

Build my first tourSee pricing

MIT-licensed — no signup, no credit card. Pay once, only when you ship.

TourRoutePrompt

Component shown when a multi-page tour needs to navigate to a different route — surfaces an explicit "Continue" / "Skip" choice when autoNavigate is off

HeadlessTourCard

HeadlessTourCard: unstyled card primitive exposing step data, actions, and positioning via render props for custom UIs

On this page

ImportWhy Headless?Basic ExampleAvailable Headless ComponentsHooks for Full ControlCombining with Styled ComponentsRelated