React Tip Magic ✨

A thoughtfully crafted tooltip library for React—simple to use, delightful to experience.

Why React Tip Magic?

Tooltips seem simple, but getting them right takes care. They should appear when needed, stay out of the way when not, and feel natural as users navigate your interface.

React Tip Magic handles the details so you don't have to—positioning, transitions, accessibility, keyboard support—all with a clean, declarative API.

Quick Start

npm install @galangel/react-tip-magic

import { TipMagicProvider } from '@galangel/react-tip-magic';
import '@galangel/react-tip-magic/styles.css';

function App() {
  return (
    <TipMagicProvider>
      <YourApp />
    </TipMagicProvider>
  );
}

That's it. Now add data-tip to any element:

<button data-tip="Save your changes">Save</button>

Tooltips

The core of React Tip Magic. One tooltip instance that gracefully moves between elements, providing a smooth, cohesive experience.

Basic Usage

<button data-tip="Click to save">Save</button>
<button data-tip="Undo last action">Undo</button>

With Keyboard Shortcuts

Display shortcuts alongside your tooltips using the data-tip-shortcut attribute:

<button data-tip="Copy" data-tip-shortcut="⌘C">Copy</button>
<button data-tip="Paste" data-tip-shortcut="⌘V">Paste</button>
<button data-tip="Save" data-tip-shortcut="⌘S">Save</button>

Positioning & Behavior

{
  /* Position control */
}
<button data-tip="Below the button" data-tip-placement="bottom">
  Hover me
</button>;

{
  /* Smooth transitions between grouped elements */
}
<nav>
  <a data-tip="Home" data-tip-move data-tip-group="nav">
    Home
  </a>
  <a data-tip="About" data-tip-move data-tip-group="nav">
    About
  </a>
  <a data-tip="Contact" data-tip-move data-tip-group="nav">
    Contact
  </a>
</nav>;

{
  /* Interactive tooltips that stay visible on hover */
}
<span data-tip="Click <a href='#'>here</a> to learn more" data-tip-html data-tip-interactive>
  More info
</span>;

Guided Tours

Walk users through your interface with step-by-step tours. Helpful for onboarding, feature introductions, or contextual guidance.

import { useTour } from '@galangel/react-tip-magic';

function App() {
  const tour = useTour({
    steps: [
      { target: 'dashboard', title: 'Welcome', content: 'This is your dashboard.' },
      { target: 'create-btn', title: 'Create', content: 'Click here to get started.' },
    ],
    // Built-in Back/Next controls are off by default—turn them on for multi-step tours
    navigation: { showControls: true },
    progress: { show: true },
  });

  return (
    <div>
      <nav data-tip-id="dashboard">Dashboard</nav>
      <button data-tip-id="create-btn" onClick={tour.start}>
        New Project
      </button>
    </div>
  );
}

useTour is headless by default: leave navigation.showControls unset and render your own controls from the returned next, prev, end and progress.

const tour = useTour({ steps });

{
  tour.isActive && (
    <div>
      <span>
        {tour.progress.current} of {tour.progress.total}
      </span>
      <button onClick={tour.prev} disabled={tour.currentStep?.isFirst}>
        Back
      </button>
      <button onClick={tour.next}>{tour.currentStep?.isLast ? 'Finish' : 'Next'}</button>
    </div>
  );
}

Step content is HTML

Step content is injected as HTML so that titles, media and controls work. Use text instead when the value is plain text the library should escape for you:

{ target: 'profile', text: `Signed in as ${user.name}` }

Exactly one of content or text is required — a step with neither, or with both, won't compile. For markup with an interpolated value, keep content and escape the value with the exported escapeHtml:

import { escapeHtml } from '@galangel/react-tip-magic';

{ target: 'profile', content: `Signed in as <b>${escapeHtml(user.name)}</b>` }

When a target isn't there

start() returns false and changes nothing—no onStart, no onStepChange—if no step's target is in the DOM, so a tour that can't render never reports itself as shown. Supply onTargetMissing to handle it yourself (and to keep the library off console.warn):

const tour = useTour({
  steps,
  onTargetMissing: (step) => {
    logger.warn('tour target missing', { target: step.target });
    return 'skip'; // or end the tour, which is the default
  },
});

if (tour.start()) {
  markTourAsSeen();
}

Recovery depends on the direction of travel: next() skips or ends the tour, while prev() and goTo() leave it where it is — the step on screen is still fine. goTo() never skips, so it lands on the step you asked for or returns false.

Where focus lands

A tour panel is a dialog, so focus moves into it when a step opens. autoFocus picks which element inside it:

const tour = useTour({
  steps,
  // 'panel' (default) | 'primary' — Next/Finish, so Enter advances | false — leave focus alone
  navigation: { showControls: true, autoFocus: 'primary' },
});

'primary' falls back to the panel when a step renders no Next/Finish button — never to the close button. Overridable per step via step.navigation.autoFocus.

Tours also support progress indicators, keyboard support, and backdrop highlighting (focus: true, or focus: { dismissOnClick: true } to let a click on the backdrop end the tour)—all configurable to fit your needs.

Tip Advisor

A keyboard shortcut discovery menu. Press a key (F1 by default) to reveal all available shortcuts in your interface, with fuzzy search to quickly find what you need.

import { TipAdvisor } from '@galangel/react-tip-magic';

function App() {
  return (
    <TipMagicProvider>
      <div className="toolbar">
        <button data-tip="Copy" data-tip-shortcut="⌘C">
          Copy
        </button>
        <button data-tip="Paste" data-tip-shortcut="⌘V">
          Paste
        </button>
        <button data-tip="Save" data-tip-shortcut="⌘S">
          Save
        </button>
      </div>

      {/* Press F1 to open the advisor */}
      <TipAdvisor />
    </TipMagicProvider>
  );
}

Features:

• Fuzzy search with highlighted matches
• Keyboard navigation (arrow keys + Enter)
• Hover to preview tooltip locations
• Click to trigger the associated element

Data Attributes

| Attribute | Description | Example | | ---------------------- | ----------------------------------- | ----------------------------- | | data-tip | Tooltip content | data-tip="Hello" | | data-tip-shortcut | Keyboard shortcut badge | data-tip-shortcut="⌘S" | | data-tip-id | Element identifier for tours | data-tip-id="welcome" | | data-tip-placement | Position (top, bottom, left, right) | data-tip-placement="bottom" | | data-tip-delay | Show delay in ms | data-tip-delay="500" | | data-tip-hide-delay | Hide delay in ms | data-tip-hide-delay="100" | | data-tip-disabled | Disable tooltip | data-tip-disabled | | data-tip-html | Parse content as HTML | data-tip-html | | data-tip-interactive | Keep tooltip on hover | data-tip-interactive | | data-tip-move | Smooth move transition | data-tip-move | | data-tip-group | Group for transitions | data-tip-group="nav" | | data-tip-no-arrow | Hide tooltip arrow | data-tip-no-arrow |

Programmatic API

For more control, use the useTipMagic hook:

import { useTipMagic } from '@galangel/react-tip-magic';

function MyComponent() {
  const { tooltip } = useTipMagic();

  const handleClick = () => {
    tooltip.show('#my-element', 'Dynamic content');
  };

  return (
    <button id="my-element" onClick={handleClick}>
      Click me
    </button>
  );
}

Built With

• React 18+ with modern hooks
• TypeScript for type safety
• Floating UI for positioning
• Storybook for documentation

License

Apache-2.0