@buratii/react-tooltip-guide

A lightweight, stylable guided tooltip overlay for React. It highlights target elements with a mask and shows a tooltip with content and navigation (Back, Next, Finish).

• Repository: https://github.com/Buratii/react-tooltip-guide
• npm: https://www.npmjs.com/package/@buratii/react-tooltip-guide

Installation

npm install @buratii/react-tooltip-guide

Peer dependencies: react and react-dom (v17+).

Quick Start

import React from "react";
import {
  TooltipGuideProvider,
  TooltipOverlay,
  useTooltipGuide,
  type TooltipStep,
} from "@buratii/react-tooltip-guide";

function StartTourButton() {
  const { start } = useTooltipGuide();

  const steps: TooltipStep[] = [
    { selector: "#input-search", title: "Search", content: "Type to filter users" },
    { selector: "#button-add", title: "New user", content: "Click to create a new record" },
    { selector: "#users-table", title: "Table", content: "Results will appear here" },
  ];

  return <button onClick={() => start(steps)}>Start tour</button>;
}

// Example component with IDs to be used by selectors
function UsersPage() {
  return (
    <div>
      <input id="input-search" placeholder="Search users..." />
      <button id="button-add">Add</button>
      <table id="users-table">
        <thead>
          <tr><th>Name</th><th>Email</th></tr>
        </thead>
        <tbody>
          <tr><td>Jane Doe</td><td>[email protected]</td></tr>
        </tbody>
      </table>
    </div>
  );
}

export default function App() {
  return (
    <TooltipGuideProvider>
      <UsersPage />
      <StartTourButton />
      {/* Overlay should be mounted once, usually near the app root */}
      <TooltipOverlay />
    </TooltipGuideProvider>
  );
}

API

• TooltipGuideProvider: Provides tour context. Props: onFinish?: () => void.
• useTooltipGuide(): Returns { isActive, stepIndex, steps, currentStep, start(steps), back(), next(), finish() }.
• TooltipOverlay props:
  • classNames?: override class names for individual parts (see below).
  • styles?: override inline styles for individual parts (see below).
  • gap?: space between target and tooltip. Default: 12.
  • maskBorderRadius?: corner radius for the highlighted cutout. Default: 16.
  • renderStep?(params): custom renderer for the tooltip content.

Types

export type Placement = "top" | "bottom" | "left" | "right" | "auto";

export interface TooltipStep {
  // Preferred: CSS selector for the target element
  selector?: string;
  // Fallback: element id (used when selector is absent)
  id?: string;
  title?: string;
  content?: string;
  placement?: Placement; // currently auto top/bottom
}

export interface ClassNames {
  mask?: string;
  tooltip?: string;
  arrow?: string;
  title?: string;
  content?: string;
  footer?: string;
  button?: string;
  backButton?: string;
  nextButton?: string;
  finishButton?: string;
}

export interface Styles {
  mask?: React.CSSProperties;
  tooltip?: React.CSSProperties;
  arrow?: React.CSSProperties;
  title?: React.CSSProperties;
  content?: React.CSSProperties;
  footer?: React.CSSProperties;
  button?: React.CSSProperties;
  backButton?: React.CSSProperties;
  nextButton?: React.CSSProperties;
  finishButton?: React.CSSProperties;
}

export interface RenderStepParams {
  step: TooltipStep;
  index: number;
  total: number;
  controls: { back: () => void; next: () => void; finish: () => void };
}

Positioning

• Auto placement: Chooses bottom by default, flips to top if there isn’t enough space.
• Smart arrow: Horizontally centers toward the target and clamps within the tooltip.
• Scrolling: Ensures the target is scrolled into view when a step activates.

Custom Rendering

<TooltipOverlay
  renderStep={({ step, index, total, controls }) => (
    <div>
      {step.title && <h3 style={{ margin: 0 }}>{step.title}</h3>}
      {step.content && <p style={{ marginTop: 6 }}>{step.content}</p>}
      <div style={{ display: "flex", gap: 8, justifyContent: "flex-end" }}>
        {index > 0 && <button onClick={controls.back}>Back</button>}
        {index + 1 < total ? (
          <button onClick={controls.next}>Next</button>
        ) : (
          <button onClick={controls.finish}>Got it!</button>
        )}
      </div>
    </div>
  )}
/>

Styling

• Class overrides: Provide classNames to target mask, tooltip, arrow, title, content, footer, button, backButton, nextButton, finishButton.
• Inline overrides: Provide styles with the same keys to override inline styles.
• Mask: Use styles.mask.boxShadow to customize the dimmed backdrop. Clicking the mask finishes the tour.

Tailwind example:

<TooltipOverlay
  classNames={{
    tooltip: "bg-gray-800 text-white rounded-lg shadow-xl",
    title: "font-bold",
    content: "text-sm mt-1",
    button: "px-3 py-1 hover:opacity-90",
  }}
  styles={{ mask: { boxShadow: "0 0 0 9999px rgba(0,0,0,0.7)" } }}
/>

Notes

• Clicking the dark mask finishes the tour immediately.
• TooltipStep.selector is preferred over id and should point to a stable element.
• The overlay uses a high z-index to appear above most UIs.
• All TypeScript types are exported from the package entry.

Local Build

This package uses tsup to build CJS/ESM bundles and types.

npm install
npm run build

Publishing

1. Ensure the name in package.json is correct (e.g., @buratii/react-tooltip-guide).
2. Log in: npm login.
3. Publish: npm publish --access public.

License

MIT