User Tour Kit

https://usertourkit.com/docs
Admin
User Tour Kit is an open-source headless React library for building accessible product tours,...
Tokens:613,706
Snippets:6,753
Trust Score:3.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install and Run Dashboard Example

Source: https://usertourkit.com/docs/examples/dashboard

Instructions to clone the repository, install dependencies, and run the dashboard example locally. No license keys are needed for development on localhost.

```bash
git clone https://github.com/domidex01/tour-kit
cd tour-kit
pnpm install
pnpm --filter dashboard-next dev
```

--------------------------------

### Quick Example: Basic Checklist Setup

Source: https://usertourkit.com/docs/checklists/components

Demonstrates how to set up and display a basic checklist using the ChecklistProvider and Checklist components. Ensure you have the necessary components imported from '@tour-kit/checklists'.

```javascript
import {
  ChecklistProvider,
  Checklist,
  ChecklistTask,
  ChecklistProgress,
} from '@tour-kit/checklists';

const checklist = {
  id: 'onboarding',
  title: 'Get Started',
  tasks: [
    { id: 'step1', title: 'Create account' },
    { id: 'step2', title: 'Verify email' },
    { id: 'step3', title: 'Complete profile' },
  ],
};

function App() {
  return (
    <ChecklistProvider checklists={[checklist]}> 
      <Checklist
        checklistId="onboarding"
        showHeader
        showProgress
      />
    </ChecklistProvider>
  );
}
```

--------------------------------

### Complete PostHog and Analytics Provider Setup

Source: https://usertourkit.com/docs/analytics/plugins/posthog

This example shows how to initialize the PostHog SDK and set up the AnalyticsProvider with the posthogPlugin. It includes user identification logic. Ensure NEXT_PUBLIC_POSTHOG_KEY is set in your environment variables.

```javascript
'use client'

import { AnalyticsProvider, posthogPlugin } from '@tour-kit/analytics'
import { PostHogProvider } from 'posthog-js/react'
import posthog from 'posthog-js'
import { useEffect } from 'react'

// Initialize PostHog SDK
if (typeof window !== 'undefined') {
  posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
    api_host: 'https://app.posthog.com',
    autocapture: false,
    capture_pageview: false,
    session_recording: {
      recordCrossOriginIframes: true
    }
  })
}

export function Providers({ children, user }) {
  useEffect(() => {
    if (user) {
      posthog.identify(user.id, {
        email: user.email,
        name: user.name
      })
    }
  }, [user])

  return (
    <PostHogProvider client={posthog}>
      <AnalyticsProvider
        config={{
          plugins: [
            posthogPlugin({
              apiKey: process.env.NEXT_PUBLIC_POSTHOG_KEY!
            })
          ],
          userId: user?.id
        }}
      >
        {children}
      </AnalyticsProvider>
    </PostHogProvider>
  )
}
```

--------------------------------

### Complete Tour Example with Various Advance Events

Source: https://usertourkit.com/docs/core/hooks/use-advance-on

A comprehensive React example demonstrating a tour with steps that advance on click, input, and custom events. Includes setup for Tour, TourStep, TourCard, and TourOverlay components.

```javascript
import {
  Tour,
  TourStep,
  TourCard,
  TourOverlay,
} from '@tour-kit/react';
import { dispatchAdvanceEvent } from '@tour-kit/core';

function InteractiveTour() {
  return (
    <Tour id="interactive-demo">
      {/* Step 1: Click to advance */}
      <TourStep
        target="#start-button"
        title="Get Started"
        content="Click this button to begin"
        advanceOn={{ event: 'click', selector: '#start-button' }}
      />

      {/* Step 2: Type to advance (with validation) */}
      <TourStep
        target="#name-input"
        title="Enter Your Name"
        content="Type at least 2 characters"
        advanceOn={{
          event: 'input',
          selector: '#name-input',
          handler: () => {
            const value = document.querySelector('#name-input')?.value;
            return value?.length >= 2;
          },
        }}
      />

      {/* Step 3: Custom event (API call completion) */}
      <TourStep
        target="#save-button"
        title="Save Your Changes"
        content="Click save and wait for confirmation"
        advanceOn={{ event: 'custom', selector: '#save-button' }}
      />

      <TourOverlay />
      <TourCard />
    </Tour>
  );
}

// In your save handler:
async function handleSave() {
  await saveData();
  dispatchAdvanceEvent('#save-button');
}
```

--------------------------------

### Create a Basic Product Tour

Source: https://usertourkit.com/docs/getting-started/quick-start

This example demonstrates how to set up a multi-step tour using the Tour, TourStep, and useTour hook from @tour-kit/react. It includes two steps targeting specific DOM elements and a button to start the tour.

```typescript
'use client';

import { Tour, TourStep, useTour } from '@tour-kit/react';

export default function Page() {
  const { start } = useTour('welcome');

  return (
    <Tour id="welcome">
      <TourStep
        target="#hero"
        title="Welcome!"
        content="This is your first tour step."
        placement="bottom"
      />
      <TourStep
        target="#features"
        title="Features"
        content="Explore our features here."
        placement="right"
      />

      <main>
        <button onClick={() => start()}>Start Tour</button>
        <section id="hero">Hero Section</section>
        <section id="features">Features</section>
      </main>
    </Tour>
  );
}
```

--------------------------------

### Complete TourCard Example

Source: https://usertourkit.com/docs/react/components/tour-card

A comprehensive example demonstrating the integration of TourCard and its sub-components within a full Tour setup. This includes TourStep definitions, TourOverlay, and custom styling for the card.

```jsx
import {
  Tour,
  TourStep,
  TourCard,
  TourCardHeader,
  TourCardContent,
  TourCardFooter,
  TourProgress,
  TourNavigation,
  TourClose,
  TourOverlay,
} from '@tour-kit/react';

function App() {
  return (
    <Tour id="demo">
      <TourStep target="#btn" title="Welcome" content="Hello world!" />
      <TourStep target="#nav" title="Navigation" content="Explore here." />

      <TourOverlay />

      <TourCard className="w-80">
        <TourCardHeader>
          <TourClose />
        </TourCardHeader>
        <TourCardContent />
        <TourCardFooter>
          <TourProgress />
          <TourNavigation />
        </TourCardFooter>
      </TourCard>

      <MainApp />
    </Tour>
  );
}
```

--------------------------------

### Install with npm

Source: https://usertourkit.com/docs/checklists

Install the @tour-kit/checklists package using npm.

```bash
npm install @tour-kit/checklists
```

--------------------------------

### Production Dashboard Example

Source: https://usertourkit.com/docs/guides/adoption-analytics

This example shows a complete setup for adoption analytics in a production dashboard. It configures analytics providers, defines features with adoption criteria, and sets up nudge notifications.

```typescript
'use client';

import { AnalyticsProvider, useAnalytics } from '@tour-kit/analytics';
import { AdoptionProvider, useAdoptionStats } from '@tour-kit/adoption';
import { segmentPlugin } from '@/lib/analytics';

const features = [
  {
    id: 'dark-mode',
    name: 'Dark Mode',
    category: 'appearance',
    trigger: '#dark-mode-toggle',
    adoptionCriteria: { minUses: 3, recencyDays: 30 },
  },
  {
    id: 'shortcuts',
    name: 'Keyboard Shortcuts',
    category: 'productivity',
    trigger: { event: 'keyboard:shortcut' },
    adoptionCriteria: { minUses: 5, recencyDays: 14 },
  },
  {
    id: 'export',
    name: 'Export Data',
    category: 'data',
    trigger: '#export-button',
    adoptionCriteria: { minUses: 2, recencyDays: 60 },
  },
  {
    id: 'integrations',
    name: 'Third-party Integrations',
    category: 'integrations',
    trigger: '#integrations-tab',
    adoptionCriteria: { minUses: 1, recencyDays: 90 },
  },
];

export default function AdoptionAnalyticsPage() {
  return (
    <AnalyticsProvider plugins={[segmentPlugin]} enabled={true}>
      <AdoptionProvider
        features={features}
        storage={{ type: 'localStorage', key: 'feature-adoption' }}
        nudge={{
          enabled: true,
          cooldown: 86400000, // 24 hours
          maxPerSession: 3,
        }}
        onAdoption={(feature) => {
          console.log('Adopted:', feature);
        }}
        onChurn={(feature) => {
          console.warn('Churned:', feature);
        }}
      >
        <AdoptionDashboard />
      </AdoptionProvider>
    </AnalyticsProvider>
  );
}

```

--------------------------------

### Install with pnpm

Source: https://usertourkit.com/docs/checklists

Install the @tour-kit/checklists package using pnpm.

```bash
pnpm add @tour-kit/checklists
```

--------------------------------

### Install with yarn

Source: https://usertourkit.com/docs/checklists

Install the @tour-kit/checklists package using yarn.

```bash
yarn add @tour-kit/checklists
```

--------------------------------

### Install @tour-kit/scheduling

Source: https://usertourkit.com/docs/scheduling

Install the scheduling package using pnpm.

```bash
pnpm add @tour-kit/scheduling
```

--------------------------------

### Install UserTourKit Adoption with npm

Source: https://usertourkit.com/docs/adoption

Install the adoption and core packages using npm.

```bash
npm install @tour-kit/adoption @tour-kit/core
```

--------------------------------

### Admin Dashboard Page Setup

Source: https://usertourkit.com/docs/adoption/dashboard

Set up the Admin Dashboard page by importing `AdoptionDashboard` and `AdoptionFilters`. This example shows how to manage filter state and pass it to the components for a dynamic view.

```javascript
import { AdoptionDashboard, AdoptionFilters } from '@tour-kit/adoption'

export default function AdminDashboard() {
  const [filters, setFilters] = useState({
    status: 'all',
    category: 'all',
    search: '',
  })

  return (
    <div className="container mx-auto p-6">
      <div className="flex justify-between items-center mb-6">
        <h1 className="text-3xl font-bold">Feature Adoption</h1>
        <AdoptionFilters filters={filters} onChange={setFilters} />
      </div>

      <AdoptionDashboard filters={filters} />
    </div>
  )
}
```

--------------------------------

### Install UserTourKit Checklists with npm

Source: https://usertourkit.com/docs/guides/checklists-tours

Install the necessary UserTourKit packages using npm.

```bash
npm install @tour-kit/react @tour-kit/checklists
```

--------------------------------

### Install lottie-web with npm

Source: https://usertourkit.com/docs/media/components/lottie-player

Install the `lottie-web` peer dependency using npm.

```bash
npm install lottie-web
```

--------------------------------

### Install UserTourKit Adoption with pnpm

Source: https://usertourkit.com/docs/adoption

Install the adoption and core packages using pnpm.

```bash
pnpm add @tour-kit/adoption @tour-kit/core
```

--------------------------------

### Install lottie-web with pnpm

Source: https://usertourkit.com/docs/media/components/lottie-player

Install the `lottie-web` peer dependency using pnpm.

```bash
pnpm add lottie-web
```

--------------------------------

### Install UserTourKit Adoption with yarn

Source: https://usertourkit.com/docs/adoption

Install the adoption and core packages using yarn.

```bash
yarn add @tour-kit/adoption @tour-kit/core
```

--------------------------------

### Install lottie-web with yarn

Source: https://usertourkit.com/docs/media/components/lottie-player

Install the `lottie-web` peer dependency using yarn.

```bash
yarn add lottie-web
```

--------------------------------

### Install Base UI with bun

Source: https://usertourkit.com/docs/guides/base-ui

Install the Base UI React components using bun.

```bash
bun add @base-ui-components/react
```

--------------------------------

### Install Testing Dependencies

Source: https://usertourkit.com/docs/guides/testing

Install the necessary testing libraries for Tour Kit.

```bash
pnpm add -D @tour-kit/testing-library @testing-library/react @testing-library/user-event vitest jsdom
```

--------------------------------

### Resume Tour Example

Source: https://usertourkit.com/docs/core/hooks/use-persistence

Example of how to resume a tour from the current step using usePersistence and useTour.

```APIDOC
## Resume Tour

### Description
Resume a tour from the last saved step. This example demonstrates how to use `currentStep` from `usePersistence` with the `start` function from `useTour`.

### Example
```javascript
import { useEffect } from 'react';
import { usePersistence } from '@tour-kit/core';
import { useTour } from '@tour-kit/core'; // Assuming useTour is also in @tour-kit/core

function YourComponent() {
  const { currentStep } = usePersistence('tour-id');
  const { start } = useTour('tour-id');

  useEffect(() => {
    if (currentStep !== null && currentStep > 0) {
      start(currentStep);
    }
  }, [currentStep, start]);

  // ... rest of your component
}
```
```

--------------------------------

### Install Base UI with npm

Source: https://usertourkit.com/docs/guides/base-ui

Install the Base UI React components using npm.

```bash
npm install @base-ui-components/react
```

--------------------------------

### Install Tour Kit Core and React Packages

Source: https://usertourkit.com/docs/guides/i18n

Install the necessary packages for internationalization and React integration.

```bash
pnpm add @tour-kit/core @tour-kit/react
```

--------------------------------

### Install UserTourKit Checklists with yarn

Source: https://usertourkit.com/docs/guides/checklists-tours

Install the necessary UserTourKit packages using yarn.

```bash
yarn add @tour-kit/react @tour-kit/checklists
```

--------------------------------

### Install Base UI with yarn

Source: https://usertourkit.com/docs/guides/base-ui

Install the Base UI React components using yarn.

```bash
yarn add @base-ui-components/react
```

--------------------------------

### Example AnalyticsProvider Configuration

Source: https://usertourkit.com/docs/analytics/types

An example of how to configure the AnalyticsProvider with custom plugins and user-specific properties. This setup is typically used at the application's root.

```typescript
import { AnalyticsProvider, type AnalyticsConfig } from '@tour-kit/analytics'

const config: AnalyticsConfig = {
  enabled: true,
  plugins: [
    posthogPlugin({ apiKey: 'phc_xxx' })
  ],
  debug: process.env.NODE_ENV === 'development',
  userId: user?.id,
  userProperties: {
    email: user?.email,
    plan: user?.plan
  },
  globalProperties: {
    app_version: '1.0.0',
    environment: 'production'
  }
}

<AnalyticsProvider config={config}>
  {children}
</AnalyticsProvider>
```

--------------------------------

### Install UserTourKit Checklists with pnpm

Source: https://usertourkit.com/docs/guides/checklists-tours

Install the necessary UserTourKit packages using pnpm.

```bash
pnpm add @tour-kit/react @tour-kit/checklists
```

--------------------------------

### Install Tour Kit with Next.js

Source: https://usertourkit.com/docs/react/adapters/next-app-router

Install the `@tour-kit/react` package along with Next.js. This command assumes you are using pnpm.

```bash
pnpm add @tour-kit/react next
```

--------------------------------

### Install Testing Library

Source: https://usertourkit.com/docs/testing-library

Install the necessary packages for testing Tour Kit with Vitest and React Testing Library.

```bash
pnpm add -D @tour-kit/testing-library @testing-library/react vitest
# or npm install --save-dev ...
```

--------------------------------

### Control Tour with useTour Hook

Source: https://usertourkit.com/docs/examples/basic-tour

Utilize the useTour hook to access functions for starting, navigating, and skipping the tour. This example shows how to start the tour with a button click.

```jsx
const { start, isActive, next, prev, skip } = useTour();

<button onClick={() => start()}>Start Tour</button>
```

--------------------------------

### Complete Example of @tour-kit/hints Usage

Source: https://usertourkit.com/docs/hints

Demonstrates how to use HintsProvider, Hint, useHint, and useHints for feature announcements and contextual help. Includes persistent and dismissible hints.

```javascript
import { HintsProvider, Hint, useHint, useHints } from '@tour-kit/hints';

function App() {
  return (
    <HintsProvider>
      {/* Feature announcement (persistent) */}
      <Hint
        id="new-dashboard"
        target="#dashboard-link"
        content="Check out the redesigned dashboard!"
        color="success"
        persist={true}
      />

      {/* Contextual help (can reopen) */}
      <Hint
        id="filter-help"
        target="#filter-button"
        content="Use filters to narrow results"
        size="sm"
      />

      <Dashboard />
      <HintControls />
    </HintsProvider>
  );
}

function HintControls() {
  const { resetAllHints } = useHints();
  const dashboard = useHint('new-dashboard');

  return (
    <div>
      {dashboard.isDismissed && (
        <button onClick={dashboard.reset}>
          Show dashboard hint again
        </button>
      )}
      <button onClick={resetAllHints}>Reset all hints</button>
    </div>
  );
}

```

--------------------------------

### Run Your Application

Source: https://usertourkit.com/docs/getting-started/quick-start

After setting up your tour, use this command to start your development server and view the tour in action. Ensure you are using pnpm.

```bash
pnpm dev
```

--------------------------------

### Start Tour Imperatively with useTourActions

Source: https://usertourkit.com/docs/guides/imperative-control

Use `useTourActions` to get imperative control over a tour, such as starting it, from a sibling component. This avoids the need for global event listeners or complex workarounds.

```jsx
import { Tour, TourStep } from '@tour-kit/react'
import { useTourActions } from '@tour-kit/core'

function ReplayButton() {
  const { isActive, start } = useTourActions('welcome')
  return (
    <button type="button" onClick={start} disabled={isActive}>
      {isActive ? 'Tour in progress…' : 'Replay onboarding'}
    </button>
  )
}

export function App() {
  return (
    <>
      <Tour id="welcome">
        <TourStep id="hero" target="#hero" content="Welcome!" />
        <TourStep id="cta" target="#cta" content="Get started here." />
      </Tour>

      {/* Sibling — NOT a descendant of <Tour> */}
      <ReplayButton />
    </>
  )
}
```

--------------------------------

### Install Base UI with pnpm

Source: https://usertourkit.com/docs/guides/base-ui

Install the Base UI React components using pnpm.

```bash
pnpm add @base-ui-components/react
```

--------------------------------

### Complete Hints Example

Source: https://usertourkit.com/docs/hints/components

Demonstrates how to integrate HintsProvider, Hint, and useHint for feature discovery and programmatic control of hints.

```javascript
import { HintsProvider, Hint, useHint } from '@tour-kit/hints';

function FeatureDiscovery() {
  return (
    <HintsProvider>
      {/* New feature announcement */}
      <Hint
        id="export-feature"
        target="#export-btn"
        content="New! Export your data to multiple formats"
        color="success"
        persist={true}
      />

      {/* Important action hint */}
      <Hint
        id="save-warning"
        target="#save-btn"
        content="Don't forget to save your changes"
        color="warning"
        position="bottom-right"
      />

      {/* Subtle help hint */}
      <Hint
        id="help-hint"
        target="#help-icon"
        content="Click for documentation"
        size="sm"
        pulse={false}
      />

      <Dashboard />
    </HintsProvider>
  );
}

// Control hints programmatically
function HintControls() {
  const exportHint = useHint('export-feature');

  return (
    <div>
      <button onClick={exportHint.show}>Show Hint</button>
      <button onClick={exportHint.dismiss}>Dismiss Forever</button>
      <button onClick={exportHint.reset}>Reset Hint</button>
      <p>Status: {exportHint.isDismissed ? 'Dismissed' : exportHint.isOpen ? 'Open' : 'Hidden'}</p>
    </div>
  );
}
```

--------------------------------

### Complete Onboarding Flow Example

Source: https://usertourkit.com/docs/guides/checklists-tours

This example demonstrates a full onboarding flow using checklists and tours. It requires importing necessary components from '@tour-kit/checklists' and '@tour-kit/core', and '@tour-kit/react'. The checklist is configured with multiple items, each potentially triggering a tour upon completion.

```tsx
'use client';

import { useState } from 'react';
import { ChecklistProvider, Checklist, ChecklistItem } from '@tour-kit/checklists';
import { TourKitProvider } from '@tour-kit/core';
import { Tour, TourStep, TourCard, TourOverlay } from '@tour-kit/react';
import { usePersistence } from '@tour-kit/core';

const checklistConfig = {
  id: 'onboarding',
  title: 'Welcome to Acme Corp',
  description: 'Get started in 3 simple steps',
  items: [
    {
      id: 'profile',
      label: 'Set up your profile',
      description: 'Add your details',
      action: { type: 'tour', tourId: 'profile-tour', label: 'Start' },
      completedWhen: { tourCompleted: 'profile-tour' },
    },
    {
      id: 'team',
      label: 'Invite your team',
      description: 'Collaborate with teammates',
      requires: ['profile'],
      action: { type: 'tour', tourId: 'team-tour', label: 'Start' },
      completedWhen: { tourCompleted: 'team-tour' },
    },
    {
      id: 'workspace',
      label: 'Create a workspace',
      description: 'Organize your projects',
      requires: ['team'],
      action: { type: 'tour', tourId: 'workspace-tour', label: 'Start' },
      completedWhen: { tourCompleted: 'workspace-tour' },
    },
  ],
};

export default function OnboardingPage() {
  const persistence = usePersistence({ keyPrefix: 'acme' });
  const [dismissed, setDismissed] = useState(false);

  const handleComplete = () => {
    persistence.markCompleted('onboarding');
    // Redirect to dashboard or show success message
    window.location.href = '/dashboard';
  };

  if (dismissed) return null;

  return (
    <TourKitProvider>
      <ChecklistProvider
        checklists={[checklistConfig]}
        onChecklistComplete={handleComplete}
      >
        <div className="min-h-screen bg-gray-50 p-8">
          <div className="max-w-4xl mx-auto">
            {/* Header */}
            <div className="text-center mb-8">
              <h1 className="text-3xl font-bold text-gray-900">
                Welcome to Acme Corp
              </h1>
              <p className="text-gray-600 mt-2">
                Let's get you set up in just a few minutes
              </p>
            </div>

            {/* Checklist */}
            <div className="bg-white rounded-lg shadow-md p-6">
              <Checklist id="onboarding" onDismiss={() => setDismissed(true)}>
                <ChecklistItem id="profile" />
                <ChecklistItem id="team" />
                <ChecklistItem id="workspace" />
              </Checklist>
            </div>

            {/* Tours */}
            <OnboardingTours />
          </div>
        </div>
      </ChecklistProvider>
    </TourKitProvider>
  );
}

function OnboardingTours() {
  return (
    <>
      <Tour id="profile-tour">
        <TourStep target="#name" title="Your Name" content="Enter your name" />
        <TourStep target="#email" title="Email" content="Verify your email" />
        <TourStep target="#avatar" title="Photo" content="Upload a photo" />
        <TourOverlay />
        <TourCard />
      </Tour>

      <Tour id="team-tour">
        <TourStep target="#invite" title="Invite" content="Add teammates" />
        <TourStep target="#roles" title="Roles" content="Set permissions" />
        <TourOverlay />
        <TourCard />
      </Tour>

      <Tour id="workspace-tour">
        <TourStep target="#new-workspace" title="Create" content="New workspace" />
        <TourStep target="#workspace-name" title="Name" content="Choose a name" />
        <TourOverlay />
        <TourCard />
      </Tour>
    </>
  );
}

```

--------------------------------

### API Backend Storage Adapter Example

Source: https://usertourkit.com/docs/guides/persistence

An example of a custom storage adapter for persisting tour state via a REST API. Assumes endpoints for GET, PUT, and DELETE operations.

```typescript
const apiStorage: Storage = {
  async getItem(key: string) {
    const res = await fetch(`/api/tour-state/${encodeURIComponent(key)}`)
    if (!res.ok) return null
    const data = await res.json()
    return JSON.stringify(data)
  },

  async setItem(key: string, value: string) {
    await fetch(`/api/tour-state/${encodeURIComponent(key)}`, {
      method: 'PUT',
      headers: { 'Content-Type': 'application/json' },
      body: value,
    })
  },

  async removeItem(key: string) {
    await fetch(`/api/tour-state/${encodeURIComponent(key)}`, {
      method: 'DELETE',
    })
  },
}
```

--------------------------------

### Complete UserTourKit Analytics Provider Setup

Source: https://usertourkit.com/docs/analytics/plugins/mixpanel

A full example of setting up the AnalyticsProvider with Mixpanel and console plugins, including user and global properties. This setup is typically placed in your application's root provider file.

```javascript
'use client'

import { AnalyticsProvider, mixpanelPlugin, consolePlugin } from '@tour-kit/analytics'
import { useUser } from '@/lib/auth'

const isDev = process.env.NODE_ENV === 'development'

export function Providers({ children }) {
  const user = useUser()

  return (
    <AnalyticsProvider
      config={{
        plugins: [
          ...(isDev ? [consolePlugin()] : []),
          mixpanelPlugin({
            token: process.env.NEXT_PUBLIC_MIXPANEL_TOKEN!,
            debug: isDev
          })
        ],
        userId: user?.id,
        userProperties: user ? {
          $email: user.email,
          $name: user.name,
          plan: user.plan,
          company: user.company
        } : undefined,
        globalProperties: {
          app_version: '1.0.0',
          platform: 'web'
        }
      }}
    >
      {children}
    </AnalyticsProvider>
  )
}
```

--------------------------------

### Install @tour-kit/hints with npm

Source: https://usertourkit.com/docs/hints

Use this command to add the library to your project if you are using npm.

```bash
npm install @tour-kit/hints
```

--------------------------------

### Basic HintsProvider Setup with useHint

Source: https://usertourkit.com/docs/hints/hooks

Demonstrates how to set up `HintsProvider` and use the `useHint` hook to access and control a specific hint. Ensure `HintsProvider` is an ancestor to any component using `useHint` or `useHints`.

```javascript
import { HintsProvider, Hint, useHint } from '@tour-kit/hints';

function App() {
  return (
    <HintsProvider>
      <Hint id="my-hint" target="#element" content="..." />
      <ChildComponent />
    </HintsProvider>
  );
}

function ChildComponent() {
  // Works because HintsProvider is an ancestor
  const hint = useHint('my-hint');
  return <button onClick={hint.show}>Show</button>;
}
```

--------------------------------

### Install @tour-kit/core with pnpm

Source: https://usertourkit.com/docs/core

Use this command to add the core package to your project. Ensure you have pnpm installed.

```bash
pnpm add @tour-kit/core
```

--------------------------------

### Complete Spotlight Example

Source: https://usertourkit.com/docs/announcements/components/spotlight

A full example demonstrating the configuration of a spotlight, including target selection, placement, overlay, and audience targeting.

```javascript
{
  id: 'new-dashboard',
  variant: 'spotlight',
  title: 'Redesigned Dashboard',
  description: 'Check out the new dashboard with improved analytics and insights.',

  media: {
    type: 'image',
    src: '/dashboard-preview.png',
  },

  primaryAction: {
    label: 'Explore Now',
    onClick: () => router.push('/dashboard'),
  },

  spotlightOptions: {
    targetSelector: '#dashboard-nav-link',
    placement: 'bottom-start',
    offset: 12,
    showOverlay: true,
    overlayOpacity: 0.7,
    padding: 8,
  },

  frequency: 'once',
  audience: [
    { field: 'hasSeenDashboard', operator: 'equals', value: false },
  ],
}
```

--------------------------------

### Google Analytics 4 Integration

Source: https://usertourkit.com/docs/media/hooks/use-media-events

Example of using useMediaEvents hook to track video start and completion with GA4.

```javascript
const handlers = useMediaEvents({
  mediaType: 'video',
  mediaSrc: '/videos/demo.mp4',
  onPlay: (event) => {
    gtag('event', 'video_start', {
      video_title: 'Product Demo',
      video_url: event.mediaSrc
    })
  },
  onComplete: (event) => {
    gtag('event', 'video_complete', {
      video_title: 'Product Demo',
      video_url: event.mediaSrc
    })
  }
})
```

--------------------------------

### Complete TourKit Setup with Next.js Pages Router

Source: https://usertourkit.com/docs/react/adapters/next-pages-router

An example demonstrating the full integration of TourKit within a Next.js application using the `MultiTourKitProvider`, `useNextPagesRouter`, and various TourKit components. This setup includes route persistence and auto-navigation.

```typescript
import {
  MultiTourKitProvider,
  useNextPagesRouter,
  Tour,
  TourStep,
  TourOverlay,
  TourCard,
  useTour,
} from '@tour-kit/react';

export function TourProvider({ children }: { children: React.ReactNode }) {
  const router = useNextPagesRouter();

  return (
    <MultiTourKitProvider
      router={router}
      routePersistence={{
        enabled: true,
        storage: 'localStorage',
      }}
      autoNavigate={true}
    >
      <Tour id="onboarding">
        <TourStep
          target="#hero"
          title="Welcome!"
          content="Let's show you around."
          route="/"
          routeMatch="exact"
        />
        <TourStep
          target="#dashboard"
          title="Dashboard"
          content="Your personal dashboard."
          route="/dashboard"
        />
        <TourStep
          target="#profile"
          title="Profile"
          content="Manage your profile here."
          route="/profile"
        />
      </Tour>

      <TourOverlay />
      <TourCard />

      {children}

      <TourButton />
    </MultiTourKitProvider>
  );
}

function TourButton() {
  const { start, isActive } = useTour();

  if (isActive) return null;

  return (
    <button onClick={() => start('onboarding')}>
      Start Tour
    </button>
  );
}
```

```typescript
import type { AppProps } from 'next/app';
import { TourProvider } from '@/components/TourProvider';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <TourProvider>
      <Component {...pageProps} />
    </TourProvider>
  );
}
```

--------------------------------

### Basic Tour Setup

Source: https://usertourkit.com/docs/react/components/tour

Demonstrates the minimal setup for the Tour component, including defining steps with target selectors and content. Use this for simple tours where advanced configuration is not needed.

```jsx
import { Tour, TourStep } from '@tour-kit/react';

<Tour
  id="onboarding"
  onComplete={() => console.log('Done!')}
>
  <TourStep target="#btn" content="Click here" />
  <YourAppContent />
</Tour>
```

--------------------------------

### Schedule Example

Source: https://usertourkit.com/docs/scheduling/types

Illustrates how to configure a basic schedule with enabled status, start and end dates, specific days of the week, and a daily time range.

```typescript
const schedule: Schedule = {
  enabled: true,
  startAt: '2024-01-15',
  endAt: '2024-12-31',
  daysOfWeek: [1, 2, 3, 4, 5],
  timeOfDay: { start: '09:00', end: '17:00' },
  useUserTimezone: true,
}
```

--------------------------------

### Full Tour Configuration Example

Source: https://usertourkit.com/docs/react/components/tour

Illustrates a comprehensive configuration of the Tour component with options for auto-start, keyboard controls, spotlight styling, and event callbacks for analytics. This example shows how to integrate TourCard and TourOverlay components.

```jsx
import { Tour, TourStep, TourCard, TourOverlay } from '@tour-kit/react';

function App() {
  return (
    <Tour
      id="welcome-tour"
      autoStart={false}
      keyboard={{ enabled: true, trapFocus: true }}
      spotlight={{ padding: 8, borderRadius: 4 }}
      onStart={() => analytics.track('tour_started')}
      onComplete={() => analytics.track('tour_completed')}
      onSkip={() => analytics.track('tour_skipped')}
    >
      <TourStep
        target="#header"
        title="Welcome!"
        content="Let's get started with a quick tour."
        placement="bottom"
      />
      <TourStep
        target="#sidebar"
        title="Navigation"
        content="Use the sidebar to explore features."
        placement="right"
      />
      <TourOverlay />
      <TourCard />
      <MainContent />
    </Tour>
  );
}
```

--------------------------------

### GitHub Actions CI/CD Setup

Source: https://usertourkit.com/docs/licensing

Configure your GitHub Actions workflow to install dependencies using a private NPM token. Ensure `NPM_TOKEN` is added to your repository secrets.

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      # Required for installing restricted @tour-kit/* pro packages
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
```

--------------------------------

### Install @tour-kit/hints with pnpm

Source: https://usertourkit.com/docs/hints

Use this command to add the library to your project if you are using pnpm.

```bash
pnpm add @tour-kit/hints
```

--------------------------------

### Custom Tour Example with Headless Components

Source: https://usertourkit.com/docs/examples/headless-custom

This example demonstrates building a tour with a completely custom UI using headless components from Tour Kit. It shows how to integrate custom overlay and card components using render props.

```javascript
'use client';

import {
  Tour,
  TourStep,
  useTour,
} from '@tour-kit/react';
import {
  TourCardHeadless,
  TourOverlayHeadless,
  TourProgressHeadless,
} from '@tour-kit/react/headless';

export default function CustomTourExample() {
  return (
    <Tour id="custom-tour">
      <TourStep
        target="#feature-1"
        title="Custom Design"
        content="This tour uses completely custom UI components."
        placement="bottom"
      />
      <TourStep
        target="#feature-2"
        title="Your Styles"
        content="Style every element exactly how you want."
        placement="right"
      />
      <TourStep
        target="#feature-3"
        title="Full Control"
        content="All positioning and accessibility handled for you."
        placement="left"
      />

      {/* Custom overlay with render prop */}
      <CustomOverlay />

      {/* Custom card with render prop */}
      <CustomCard />

      <AppContent />
    </Tour>
  );
}

// Completely custom overlay with gradient effect
function CustomOverlay() {
  return (
    <TourOverlayHeadless
      render={({ isActive, overlayStyle, cutoutStyle, targetRect }) => (
        <div
          style={{
            ...overlayStyle,
            background: 'radial-gradient(circle at center, rgba(0,0,0,0) 0%, rgba(0,0,0,0.8) 100%)',
          }}
          className="fixed inset-0 z-40 transition-opacity duration-300"
        >
          {targetRect && (
            <div
              style={{
                ...cutoutStyle,
                boxShadow: '0 0 0 4px rgba(59, 130, 246, 0.5), 0 0 20px rgba(59, 130, 246, 0.3)',
              }}
              className="rounded-lg"
            />
          )}
        </div>
      )}
    />
  );
}

// Completely custom card with render prop
function CustomCard() {
  return (
    <TourCardHeadless
      render={({
        currentStep,
        currentStepIndex,
        totalSteps,
        isFirstStep,
        isLastStep,
        next,
        prev,
        skip,
        floatingStyles,
        refs,
      }) => (
        <div
          ref={refs.setFloating}
          style={floatingStyles}
          className="z-50 w-80 animate-in fade-in slide-in-from-bottom-2 duration-200"
        >
          {/* Custom card design */}
          <div className="bg-gradient-to-br from-slate-900 to-slate-800 text-white rounded-2xl shadow-2xl border border-slate-700 overflow-hidden">
            {/* Header with step indicator */}
            <div className="px-5 py-4 border-b border-slate-700 flex items-center justify-between">
              <span className="text-sm font-medium text-blue-400">
                Step {currentStepIndex + 1} of {totalSteps}
              </span>
              <button
                onClick={skip}
                className="text-slate-400 hover:text-white transition-colors text-sm"
              >
                Skip
              </button>
            </div>

            {/* Content */}
            <div className="p-5 space-y-3">
              <h2 className="text-xl font-bold">{currentStep?.title}</h2>
              <p className="text-slate-300 leading-relaxed">
                {currentStep?.content}
              </p>
            </div>

            {/* Custom progress bar */}
            <div className="px-5">
              <TourProgressHeadless
                current={currentStepIndex + 1}
                total={totalSteps}
                render={({ current, total }) => (
                  <div className="h-1 bg-slate-700 rounded-full overflow-hidden">
                    <div
                      className="h-full bg-blue-500 transition-all duration-300"
                      style={{ width: `${(current / total) * 100}%` }}
                    />
                  </div>
                )}
              />
            </div>
          </div>
        </div>
      )}
    />
  );
}

function AppContent() {
  return (
    <div className="p-8 flex flex-col gap-4">
      <h1 className="text-4xl font-bold">Welcome to Custom Tour!</h1>
      <p className="text-lg text-gray-600">This is an example of a custom tour UI.</p>
      <div className="flex gap-4">
        <button id="feature-1" className="px-4 py-2 rounded-md bg-blue-500 text-white">Feature 1</button>
        <button id="feature-2" className="px-4 py-2 rounded-md bg-green-500 text-white">Feature 2</button>
        <button id="feature-3" className="px-4 py-2 rounded-md bg-red-500 text-white">Feature 3</button>
      </div>
    </div>
  );
}

```

--------------------------------

### Get Day of Week in Different Timezones

Source: https://usertourkit.com/docs/scheduling/utilities/day-of-week

Use `getDayOfWeek` to retrieve the day of the week for a given date and timezone. Note that the day number starts from 0 for Sunday.

```typescript
import { getDayOfWeek } from '@tour-kit/scheduling'

const date = new Date('2024-01-01T02:00:00Z') // 2am UTC on Monday

// In UTC - Monday (1)
getDayOfWeek(date, 'UTC')
// 1

// In Los Angeles (Sunday 6pm) - Sunday (0)
getDayOfWeek(date, 'America/Los_Angeles')
// 0
```

--------------------------------

### Prefixed Storage for Multi-App Example

Source: https://usertourkit.com/docs/core/utilities/storage

Demonstrates how to use `createPrefixedStorage` to isolate storage for multiple applications on the same domain, preventing key conflicts. Each application gets its own prefixed namespace.

```javascript
// Prevent collisions when multiple apps use the same storage
const mainAppTours = createPrefixedStorage(localStorage, 'main-app');
const adminTours = createPrefixedStorage(localStorage, 'admin');

mainAppTours.setItem('completed', '["welcome"]');
adminTours.setItem('completed', '["admin-tour"]');

// Stored as:
// "main-app:completed" → '["welcome"]'
// "admin:completed" → '["admin-tour"]'
```

--------------------------------

### Countdown Timer with useScheduleStatus

Source: https://usertourkit.com/docs/scheduling/hooks/use-schedule-status

Implement a countdown timer to show users when a tour will start or end. This example configures the hook to refresh the status every second for accurate countdowns.

```javascript
function TourCountdown() {
  const { isActive, nextActiveAt, nextInactiveAt } = useScheduleStatus(schedule, {
    refreshInterval: 1000, // Update every second
  })

  const targetTime = isActive ? nextInactiveAt : nextActiveAt
  if (!targetTime) return null

  const now = new Date()
  const msRemaining = targetTime.getTime() - now.getTime()
  const minutesRemaining = Math.floor(msRemaining / 60000)

  return (
    <div>
      {isActive ? (
        <p>Tour ends in {minutesRemaining} minutes</p>
      ) : (
        <p>Tour starts in {minutesRemaining} minutes</p>
      )}
    </div>
  )
}
```

--------------------------------

### Complete Modal Example

Source: https://usertourkit.com/docs/announcements/components/modal

A full example demonstrating how to configure and display a modal announcement with various options including actions, media, and tracking.

```javascript
const announcements = [
  {
    id: 'feature-launch',
    variant: 'modal',
    priority: 'high',
    title: 'New Export Feature',
    description: 'Export your data to CSV, PDF, or Excel format.',

    media: {
      type: 'image',
      src: '/export-preview.png',
      alt: 'Export feature preview',
    },

    primaryAction: {
      label: 'Try It Now',
      onClick: () => router.push('/export'),
    },

    secondaryAction: {
      label: 'Learn More',
      onClick: () => window.open('/docs/export'),
    },

    modalOptions: {
      size: 'lg',
      closeOnOverlayClick: false, // Prevent accidental closing
      showCloseButton: true,
    },

    frequency: 'once',
    onShow: () => analytics.track('modal_shown'),
    onDismiss: (reason) => analytics.track('modal_dismissed', { reason }),
  },
];

<AnnouncementModal id="feature-launch" />
```

--------------------------------

### Enable Flow Session with sessionStorage

Source: https://usertourkit.com/docs/guides/persistence

Quick start example to enable tour-scoped session persistence using sessionStorage. This allows tours to resume after a hard reload within the same tab.

```jsx
import { TourProvider } from '@tour-kit/core'

<TourProvider
  tours={[onboardingTour]}
  routePersistence={{
    enabled: true,
    flowSession: { storage: 'sessionStorage' },
  }}
>
  {children}
</TourProvider>
```

--------------------------------

### Filter Events with a Custom Plugin

Source: https://usertourkit.com/docs/analytics/plugins/custom

Implement this plugin to filter events based on specific criteria before they are sent to analytics. This example only tracks 'tour_completed' events for tours starting with 'onboarding-'.

```typescript
export function filteredPlugin(): AnalyticsPlugin {
  return {
    name: 'filtered-plugin',

    track(event: TourEvent) {
      // Only track tour completion events
      if (event.eventName !== 'tour_completed') {
        return
      }

      // Only track specific tours
      if (!event.tourId.startsWith('onboarding-')) {
        return
      }

      console.log('Tracking:', event)
      // Send to analytics
    }
  }
}
```

--------------------------------

### Complete Example of @tour-kit/checklists Usage

Source: https://usertourkit.com/docs/checklists

This example demonstrates how to set up and integrate the ChecklistProvider, ChecklistPanel, ChecklistLauncher, and various checklist components within a React application. It includes defining a checklist with tasks, dependencies, and actions, and shows how to access checklist state using the useChecklist hook.

```javascript
import {
  ChecklistProvider,
  ChecklistPanel,
  ChecklistLauncher,
  Checklist,
  ChecklistTask,
  ChecklistProgress,
  useChecklist,
} from '@tour-kit/checklists';

const setupChecklist = {
  id: 'setup',
  title: 'Account Setup',
  description: 'Get your account ready in 3 steps',
  dismissible: true,
  hideOnComplete: true,
  tasks: [
    {
      id: 'verify-email',
      title: 'Verify your email',
      description: 'Check your inbox for verification link',
      icon: '📧',
    },
    {
      id: 'add-payment',
      title: 'Add payment method',
      description: 'Add a credit card to enable premium features',
      icon: '💳',
      dependsOn: ['verify-email'],
      action: { type: 'navigate', url: '/settings/billing' },
    },
    {
      id: 'invite-team',
      title: 'Invite team members',
      description: 'Collaborate with your team',
      icon: '👥',
      dependsOn: ['verify-email'],
      action: { type: 'modal', modalId: 'invite-modal' },
    },
  ],
  onComplete: () => {
    console.log('Setup complete!');
    analytics.track('setup_completed');
  },
};

function App() {
  return (
    <ChecklistProvider checklists={[setupChecklist]}>
      {/* Floating panel with launcher */}
      <ChecklistPanel checklistId="setup">
        <ChecklistProgress />
        <Checklist>
          <ChecklistTask taskId="verify-email" />
          <ChecklistTask taskId="add-payment" />
          <ChecklistTask taskId="invite-team" />
        </Checklist>
      </ChecklistPanel>

      <ChecklistLauncher checklistId="setup" />

      <YourAppContent />
    </ChecklistProvider>
  );
}

function ChecklistControls() {
  const { progress, isComplete, reset } = useChecklist('setup');

  return (
    <div>
      <p>{progress.completed} of {progress.total} completed</p>
      {isComplete && (
        <button onClick={reset}>Start over</button>
      )}
    </div>
  );
}

```

--------------------------------

### Hook Return Types with useTour

Source: https://usertourkit.com/docs/getting-started/typescript

Utilize the useTour hook and its return type UseTourReturn to get typed access to tour control functions like start, next, and prev.

```typescript
import { useTour, type UseTourReturn } from '@tour-kit/react';

function MyComponent() {
  const tour: UseTourReturn = useTour('my-tour');
  // tour.start, tour.next, tour.prev, etc.}
```

--------------------------------

### Install @tour-kit/hints with yarn

Source: https://usertourkit.com/docs/hints

Use this command to add the library to your project if you are using yarn.

```bash
yarn add @tour-kit/hints
```

--------------------------------

### Loom Embed for Onboarding New Users

Source: https://usertourkit.com/docs/media/components/loom-embed

Embed a Loom video within a tour step to guide new users through setup processes. Supports autoplay for immediate playback.

```jsx
<Tour id="onboarding">
  <TourStep id="setup">
    <h2>Setting Up Your Workspace</h2>
    <LoomEmbed
      videoId="setup-walkthrough"
      title="Workspace setup tutorial"
      autoplay
    />
    <p>Watch this 2-minute guide to get started</p>
  </TourStep>
</Tour>
```

--------------------------------

### Create Storage Adapters with @tour-kit/core

Source: https://usertourkit.com/docs/hints/persistence

Demonstrates creating different storage adapters like localStorage, sessionStorage, and cookie storage. Also shows how to create a prefixed adapter to prevent key collisions.

```javascript
import {
  createStorageAdapter,
  createPrefixedStorage,
  createCookieStorage
} from '@tour-kit/core';

// localStorage (default)
const localAdapter = createStorageAdapter('localStorage');

// sessionStorage (clears on tab close)
const sessionAdapter = createStorageAdapter('sessionStorage');

// Cookies (for SSR-friendly persistence)
const cookieAdapter = createCookieStorage({ expires: 30 }); // 30 days

// With prefix to avoid collisions
const prefixedAdapter = createPrefixedStorage(localAdapter, 'myapp-hints');
```
Tokens:
Raw