vue3-tooltip

npm install vue3-tooltip

or

yarn add vue3-tooltip

⚡ Highlights

<!-- Simple as this 👇 -->
<button v-tooltip.auto.touch.primary:top="'Hello World! 👋'">
  Hover or tap me
</button>

3 seconds to install • Auto-positioning • Touch support • Full TypeScript • 3.9 KB only

✨ Features

Why developers love Vue3 Tooltip

🚀 Quick Start

Get up and running in 60 seconds!

📦 Step 1: Install

Choose your favorite package manager:

npm install vue3-tooltip
# or
yarn add vue3-tooltip
# or
pnpm add vue3-tooltip

⚙️ Step 2: Register Plugin

Add to your Vue app (usually main.ts or main.js):

import { createApp } from 'vue';
import VueTooltip from 'vue3-tooltip';
import 'vue3-tooltip/tooltip.css';  // 👈 Don't forget styles!

const app = createApp(App);
app.use(VueTooltip);  // 👈 Registers directive & component
app.mount('#app');

🎯 Step 3: Use It!

Option A: As a directive (simplest way)

<button v-tooltip="'Hello World!'">
  Hover me 👋
</button>

Option B: As a component (more control)

<Tooltip>
  <template #text>Hover me 👋</template>
  <template #tooltip>Hello World!</template>
</Tooltip>

That's it! 🎉 You're ready to go!

💡 Examples

🎯 Smart Auto-Positioning

The tooltip automatically flips to stay visible in viewport:

<button v-tooltip.auto:bottom="'I adjust my position smartly!'">
  Near screen edge 🎯
</button>

💡 Perfect for dropdowns near screen edges - no more cut-off tooltips!

📱 Touch Device Support

Works seamlessly on mobile and tablets:

<button v-tooltip.touch="'Tap me on mobile! 📱'">
  Mobile & Desktop Ready
</button>

💡 Automatically detects touch devices and adapts behavior

🎨 Color Variants

Choose from three beautiful built-in themes:

<button v-tooltip.primary="'Clean & modern'">Primary</button>
<button v-tooltip.secondary="'Subtle & elegant'">Secondary</button>
<button v-tooltip.accent="'Bold & bright'">Accent</button>

🧭 Position Control

Place tooltips exactly where you want them:

<button v-tooltip:top="'↑ Top'">Top</button>
<button v-tooltip:bottom="'↓ Bottom'">Bottom</button>
<button v-tooltip:left="'← Left'">Left</button>
<button v-tooltip:right="'→ Right'">Right</button>

🎭 Combine Modifiers

Mix and match modifiers for powerful tooltips:

<!-- Auto-positioning + Touch + Custom color -->
<button v-tooltip.auto.touch.secondary:top="'The ultimate tooltip! 🚀'">
  All Features Combined
</button>

💡 Pro tip: Chain modifiers like .auto.touch.primary for maximum functionality!

🧩 Component API

For more complex scenarios, use the <Tooltip> component:

Props Reference

Rich Content Example

Perfect for complex HTML content:

<template>
  <Tooltip 
    position="top"
    :auto-position="true"
    :adaptive-touch="true"
  >
    <template #text>
      <button class="my-button">
        📊 View Stats
      </button>
    </template>
    
    <template #tooltip>
      <div class="rich-tooltip">
        <h4>📈 User Statistics</h4>
        <p>Active users: <strong>1,234</strong></p>
        <p>Growth: <strong style="color: #10b981">+15%</strong></p>
      </div>
    </template>
  </Tooltip>
</template>

<style scoped>
.rich-tooltip {
  min-width: 200px;
  text-align: left;
}
.rich-tooltip h4 {
  margin: 0 0 8px;
  font-size: 14px;
}
.rich-tooltip p {
  margin: 4px 0;
  font-size: 12px;
}
</style>

🎨 Customization

Match your design system effortlessly with CSS variables!

🎨 Quick Theme Override

/* In your global CSS */
:root {
  /* Make tooltips match your brand */
  --tooltip-primary-background: #2563eb;
  --tooltip-primary-color: white;
  --tooltip-d-border-radius: 12px;
  --tooltip-d-padding: 8px 16px;
}

📋 All Available Variables

:root {
  /* 📐 Layout & Positioning */
  --tooltip-d-z-index: 9999;
  --tooltip-d-z-index-hover: 9998;
  --tooltip-d-offset: 10px;
  
  /* 🎨 Appearance */
  --tooltip-d-padding: 6px 12px;
  --tooltip-d-border-radius: 6px;
  --tooltip-d-font-size: 14px;
  --tooltip-d-font-weight: 500;
  --tooltip-d-line-height: 1.4;
  
  /* 🎯 Primary Theme */
  --tooltip-primary-background: #ffffff;
  --tooltip-primary-color: #1a1a1a;
  --tooltip-primary-border: 1px solid #e5e5e5;
  --tooltip-primary-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
  
  /* 🎨 Secondary Theme */
  --tooltip-secondary-background: #f3f4f6;
  --tooltip-secondary-color: #374151;
  
  /* ✨ Accent Theme */
  --tooltip-accent-background: #10b981;
  --tooltip-accent-color: #ffffff;
  
  /* ⏱️ Animations */
  --tooltip-d-transition-duration: 0.3s;
  --tooltip-d-transition-timing: cubic-bezier(0.4, 0, 0.2, 1);
}

💡 Examples

Dark theme:

:root {
  --tooltip-primary-background: #1f2937;
  --tooltip-primary-color: #f9fafb;
  --tooltip-primary-border: 1px solid #374151;
}

Glassmorphism:

:root {
  --tooltip-primary-background: rgba(255, 255, 255, 0.8);
  --tooltip-primary-backdrop-filter: blur(10px);
  --tooltip-primary-border: 1px solid rgba(255, 255, 255, 0.3);
}

📖 Full documentation: See DOCS.md for complete customization guide

📚 Advanced Usage

🔧 TypeScript Support

Full type safety with exported types and utilities:

import type { Position, Rect, TooltipOptions } from 'vue3-tooltip';
import { getBestPosition, isTouchDevice } from 'vue3-tooltip';

// ✅ Type-safe position
const position: Position = 'bottom';

// ✅ Detect touch devices
const isTouch = isTouchDevice();

// ✅ Smart positioning for custom tooltips
const bestPos = getBestPosition(
  triggerRect,
  tooltipRect,
  'bottom'
);

🛠️ Utility Functions

Build custom tooltip solutions with our utilities:

import {
  getBestPosition,    // 🎯 Find optimal position
  checkPosition,      // ✅ Validate position fits
  isTouchDevice,      // 📱 Detect touch support
  getRect,           // 📐 Get element bounds
  checkOverflow      // 🔍 Check viewport overflow
} from 'vue3-tooltip';

Example - Custom tooltip positioning:

import { getBestPosition, getRect } from 'vue3-tooltip';

// Get element rectangles
const triggerRect = getRect(buttonElement);
const tooltipRect = getRect(tooltipElement);

// Find best position automatically
const bestPosition = getBestPosition(
  triggerRect, 
  tooltipRect, 
  'top'  // preferred position
);

console.log(bestPosition); // 'top' or alternative if top doesn't fit

🎯 Why Vue3 Tooltip?

Comparison with other popular tooltip libraries:

🌐 Browser Support

Works everywhere modern Vue 3 works:

📖 Documentation

🤝 Contributing

We welcome contributions! Help us make tooltips better for everyone.

🚀 Quick Start for Contributors

# 1️⃣ Clone the repository
git clone https://github.com/neluckoff/vue3-tooltip.git
cd vue3-tooltip

# 2️⃣ Install dependencies
npm install

# 3️⃣ Run tests (watch mode)
npm test

# 4️⃣ Build the library
npm run build

# 5️⃣ Test locally in your project
npm link

💡 Ways to Contribute

• 🐛 Report bugs - Open an issue
• ✨ Suggest features - Request a feature
• 📖 Improve docs - Fix typos, add examples
• 🧪 Add tests - Increase coverage
• 🎨 Design - Suggest UX improvements
• 💻 Code - Submit pull requests
• 🛡️ Security - Report vulnerabilities privately

📋 Please read our Contributing Guide before submitting PRs

🤝 By participating, you agree to our Code of Conduct

🔒 Found a security issue? See our Security Policy

📝 License

Released under the MIT License

Copyright © 2025 Dmitrii Lukianenko

Made with ❤️ for the Vue community

Created by @neluckoff

If you find a bug or have a feature request, please open an issue 🙏