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', message: 'This is your dashboard.' },
      { target: 'create-btn', title: 'Create', message: 'Click here to get started.' },
    ],
  });

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

Tours include navigation controls, progress indicators, keyboard support, and backdrop highlighting—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

---

Made with care for the React community