@tour-kit/hints API

API reference for @tour-kit/hints: Hint, HintHotspot, HintTooltip, useHints, useHint, and headless hint primitives

Complete API reference for the hints package. This package provides persistent hints and hotspots for feature discovery.

For prose-style docs and recipes, see the @tour-kit/hints package overview, or jump to components, headless primitives, hooks, variants, or types.

Styled Components

Hint

Main hint component combining hotspot and tooltip.

import { Hint } from '@tour-kit/hints';

<Hint
  id="feature-hint"
  target="#element"
  content="Helpful tip here"
  position="top-right"
  tooltipPlacement="bottom"
  pulse={true}
  autoShow={false}
  persist={false}
  size="default"
  color="default"
  zIndex="default"
  className="tooltip-class"
  hotspotClassName="hotspot-class"
  onClick={() => {}}
  onShow={() => {}}
  onDismiss={() => {}}
/>

Prop	Type	Default	Description
`id`	`string`	-	Unique identifier (required)
`target`	`string \| RefObject<HTMLElement>`	-	CSS selector or ref (required)
`content`	`ReactNode`	-	Tooltip content (required)
`children`	`ReactNode`	-	Custom content (overrides content)
`position`	`HotspotPosition`	`'top-right'`	Hotspot position
`tooltipPlacement`	`Placement`	`'bottom'`	Tooltip placement
`pulse`	`boolean`	`true`	Enable pulse animation
`autoShow`	`boolean`	`false`	Auto-show on mount
`persist`	`boolean`	`false`	Permanent dismiss on close
`size`	`'default' \| 'sm' \| 'lg'`	`'default'`	Hotspot size
`color`	`'default' \| 'secondary' \| 'destructive' \| 'success' \| 'warning'`	`'default'`	Hotspot color
`zIndex`	`'default' \| 'high'`	`'default'`	z-index level
`className`	`string`	-	Tooltip CSS class
`hotspotClassName`	`string`	-	Hotspot CSS class
`onClick`	`() => void`	-	Hotspot click handler
`onShow`	`() => void`	-	Show callback
`onDismiss`	`() => void`	-	Dismiss callback

HintHotspot

Standalone pulsing indicator.

import { HintHotspot } from '@tour-kit/hints';

<HintHotspot
  targetRect={domRect}
  position="top-right"
  isOpen={false}
  asChild={false}
  size="default"
  color="default"
  pulse={true}
  zIndex="default"
  className="custom-hotspot"
  onClick={() => {}}
/>

Prop	Type	Default	Description
`targetRect`	`DOMRect`	-	Target bounding rect (required)
`position`	`HotspotPosition`	-	Position relative to target (required)
`isOpen`	`boolean`	`false`	Whether tooltip is open
`asChild`	`boolean`	`false`	Merge props to child
`size`	`'default' \| 'sm' \| 'lg'`	`'default'`	Size variant
`color`	`string`	`'default'`	Color variant
`pulse`	`boolean`	`true`	Enable pulse
`zIndex`	`'default' \| 'high'`	`'default'`	z-index

HintTooltip

Floating tooltip component.

import { HintTooltip } from '@tour-kit/hints';

<HintTooltip
  target={htmlElement}
  placement="bottom"
  onClose={() => {}}
  size="default"
  zIndex="default"
  asChild={false}
  closeButton={<CustomClose />}
>
  Tooltip content
</HintTooltip>

Prop	Type	Default	Description
`target`	`HTMLElement`	-	Anchor element (required)
`placement`	`Placement`	`'bottom'`	Position relative to target
`onClose`	`() => void`	-	Close callback (required)
`children`	`ReactNode`	-	Content (required)
`closeButton`	`ReactNode`	-	Custom close button
`asChild`	`boolean`	`false`	Merge props to child
`size`	`'default' \| 'sm' \| 'lg'`	`'default'`	Size variant
`zIndex`	`'default' \| 'high'`	`'default'`	z-index

Headless Components

Import from @tour-kit/hints/headless:

HintHeadless

import { HintHeadless } from '@tour-kit/hints/headless';

<HintHeadless
  id="custom-hint"
  target="#element"
  content="Content"
  position="top-right"
  tooltipPlacement="bottom"
  pulse={true}
  autoShow={false}
  persist={false}
  render={({
    isOpen,
    isDismissed,
    show,
    hide,
    dismiss,
    targetElement,
    targetRect,
    hotspotRef,
    position,
    tooltipPlacement,
    pulse,
    content,
  }) => (
    // Custom UI
  )}
/>

HintHotspotHeadless

import { HintHotspotHeadless } from '@tour-kit/hints/headless';

<HintHotspotHeadless
  targetRect={rect}
  position="top-right"
  isOpen={false}
  render={({
    position,  // { top, left }
    isOpen,
    targetRect,
  }) => (
    // Custom hotspot UI
  )}
/>

HintTooltipHeadless

import { HintTooltipHeadless } from '@tour-kit/hints/headless';

<HintTooltipHeadless
  target={element}
  placement="bottom"
  onClose={handleClose}
  size="default"
  zIndex="default"
  render={({
    floatingStyles,
    refs,
    context,
  }) => (
    <div ref={refs.setFloating} style={floatingStyles}>
      Custom tooltip
    </div>
  )}
/>

Provider

HintsProvider

Context provider for hint state management.

import { HintsProvider } from '@tour-kit/hints';

<HintsProvider>
  {/* Hint components */}
</HintsProvider>

Hooks

useHint

Control a single hint by ID.

import { useHint } from '@tour-kit/hints';

const {
  isOpen,     // boolean - tooltip visible
  isDismissed, // boolean - permanently dismissed
  show,       // () => void - show tooltip
  hide,       // () => void - hide tooltip (temporary)
  dismiss,    // () => void - dismiss permanently
  reset,      // () => void - clear dismissed state
} = useHint('hint-id');

useHints

Access and control all hints.

import { useHints } from '@tour-kit/hints';

const {
  hints,          // HintState[] - all hints
  activeHint,     // string | null - currently open hint
  showHint,       // (id: string) => void
  hideHint,       // (id: string) => void
  dismissHint,    // (id: string) => void
  resetHint,      // (id: string) => void
  resetAllHints,  // () => void
  isHintVisible,  // (id: string) => boolean
  isHintDismissed, // (id: string) => boolean
} = useHints();

useHintsContext

Low-level context access.

import { useHintsContext } from '@tour-kit/hints';

const context = useHintsContext(); // HintsContextValue

UI Variants

CVA variant exports for customization:

import {
  hintHotspotVariants,
  hintTooltipVariants,
  hintCloseVariants,
} from '@tour-kit/hints';

// Types
import type {
  HintHotspotVariants,
  HintTooltipVariants,
  HintCloseVariants,
} from '@tour-kit/hints';

Hotspot Variants

{
  size: 'default' | 'sm' | 'lg',
  color: 'default' | 'secondary' | 'destructive' | 'success' | 'warning',
  pulse: boolean,
  zIndex: 'default' | 'high',
}

{
  size: 'default' | 'sm' | 'lg',
  zIndex: 'default' | 'high',
}

Close Button Variants

{
  position: 'default' | 'inside',
  size: 'default' | 'sm',
}

Types

HintConfig

interface HintConfig {
  id: string;
  target: string | React.RefObject<HTMLElement | null>;
  content: React.ReactNode;
  position?: HotspotPosition;
  tooltipPlacement?: Placement;
  pulse?: boolean;
  autoShow?: boolean;
  persist?: boolean;
  onClick?: () => void;
  onShow?: () => void;
  onDismiss?: () => void;
}

HintState

interface HintState {
  id: string;
  isOpen: boolean;
  isDismissed: boolean;
}

HotspotPosition

type HotspotPosition =
  | 'top-left'
  | 'top-right'
  | 'bottom-left'
  | 'bottom-right'
  | 'center';

HintsContextValue

interface HintsContextValue {
  hints: Map<string, HintState>;
  activeHint: string | null;
  registerHint: (id: string) => void;
  unregisterHint: (id: string) => void;
  showHint: (id: string) => void;
  hideHint: (id: string) => void;
  dismissHint: (id: string) => void;
  resetHint: (id: string) => void;
  resetAllHints: () => void;
}

Placement

Re-exported from @tour-kit/core:

type Placement =
  | 'top' | 'top-start' | 'top-end' | 'top-center'
  | 'bottom' | 'bottom-start' | 'bottom-end' | 'bottom-center'
  | 'left' | 'left-start' | 'left-end' | 'left-center'
  | 'right' | 'right-start' | 'right-end' | 'right-center';

Hotspot Variants & Props

Three built-in hotspot variants ship with @tour-kit/hints. Select one via <HintHotspot variant="badge" /> or render the variant components directly.

// Variant name discriminator
type HintHotspotVariantName = 'badge' | 'beacon-with-label' | 'what-s-new-pill';

interface HintBadgeProps extends Omit<React.ComponentPropsWithoutRef<'button'>, 'color'> {
  targetRect: DOMRect;
  position: HotspotPosition;
  /** Numeric badge value (clamps to "99+" above 99) */
  count?: number;
  isOpen?: boolean;
  asChild?: boolean;
}

interface HintBeaconWithLabelProps extends Omit<React.ComponentPropsWithoutRef<'button'>, 'color'> {
  targetRect: DOMRect;
  position: HotspotPosition;
  /** Visible label adjacent to the beacon — also surfaced via aria-label */
  label: string;
  /** Which side the label sits on; defaults to "right" */
  side?: 'left' | 'right';
  isOpen?: boolean;
  asChild?: boolean;
}

interface HintWhatsNewPillProps extends Omit<React.ComponentPropsWithoutRef<'button'>, 'color'> {
  targetRect: DOMRect;
  position: HotspotPosition;
  label: string;
  isOpen?: boolean;
  asChild?: boolean;
}

See Hint variants.

Utilities

cn

Class name utility.

import { cn } from '@tour-kit/hints';

cn('base', condition && 'conditional', className);

Slot Components

import { Slot, Slottable, UnifiedSlot } from '@tour-kit/hints';

UI Library Context

import { UILibraryProvider, useUILibrary } from '@tour-kit/hints';

<UILibraryProvider library="radix">
  {children}
</UILibraryProvider>

const library = useUILibrary(); // 'radix' | 'base-ui'

Import Paths

// Styled components
import { Hint, HintHotspot, HintTooltip, HintsProvider, useHint, useHints } from '@tour-kit/hints';

// Headless components
import { HintHeadless, HintHotspotHeadless, HintTooltipHeadless } from '@tour-kit/hints/headless';

// Variants
import { hintHotspotVariants, hintTooltipVariants } from '@tour-kit/hints';

// Types
import type { HintConfig, HintState, HotspotPosition, Placement } from '@tour-kit/hints';

For detailed documentation on each component, see the individual pages in the @tour-kit/hints section.