{"id":12340,"library":"v-tooltip","title":"Floating Vue (v-tooltip)","description":"Floating Vue, currently at version 5.x, is a robust and flexible library for creating tooltips, popovers, dropdowns, and menus in Vue 3 applications. It is the successor to the original `v-tooltip` package, having been rebranded from `floating-vue` v2.x to `v-tooltip` v5.x to streamline versioning and prevent confusion, while retaining the same underlying codebase and functionality. The library leverages `@floating-ui/dom` for efficient and precise anchor positioning, ensuring floating elements are always positioned optimally. It offers both directive-based (`v-tooltip`, `v-close-popper`) and component-based (`VDropdown`, `VTooltip`, `VMenu`) usage, supporting a wide range of interactive UI patterns. Releases are regular, with a focus on Vue 3 compatibility, performance, and improved TypeScript typings. Key differentiators include its extensive configuration options, powerful theming capabilities, and seamless integration with Vue 3's composition API.","status":"active","version":"2.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/Akryum/vue-tooltip","tags":["javascript","vue","tooltip","typescript"],"install":[{"cmd":"npm install v-tooltip","lang":"bash","label":"npm"},{"cmd":"yarn add v-tooltip","lang":"bash","label":"yarn"},{"cmd":"pnpm add v-tooltip","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For global plugin installation in a Vue 3 app. Note the package name `floating-vue` and not `v-tooltip` for the import. The `v-tooltip` name is used for the npm package, but the actual import path for v5 is `floating-vue`.","wrong":"import VTooltip from 'v-tooltip'\nVue.use(VTooltip)","symbol":"FloatingVue","correct":"import FloatingVue from 'floating-vue'\napp.use(FloatingVue)"},{"note":"To import the directive for local registration or direct use in `script setup`. The package name for import is `floating-vue`. This is the primary way to use tooltips directly on elements.","wrong":"import { vTooltip } from 'v-tooltip'","symbol":"vTooltip","correct":"import { vTooltip } from 'floating-vue'"},{"note":"To import the component for more complex popover or dropdown functionalities. Remember to import from `floating-vue`, not `v-tooltip`.","wrong":"import { VDropdown } from 'v-tooltip'","symbol":"VDropdown","correct":"import { VDropdown } from 'floating-vue'"},{"note":"For global configuration of themes or other options. Access the `options` object from `floating-vue`.","wrong":"import { options } from 'v-tooltip'","symbol":"options","correct":"import { options } from 'floating-vue'\noptions.themes.myTheme = { /* ... */ }"}],"quickstart":{"code":"<!-- App.vue -->\n<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { VTooltip, VDropdown } from 'floating-vue';\nimport 'floating-vue/dist/style.css'; // Don't forget to import the CSS\n\nconst tooltipMessage = ref('Hello from v-tooltip directive!');\nconst dropdownContent = ref('This is a dropdown menu.');\n</script>\n\n<template>\n  <main class=\"container\">\n    <h1>Floating Vue (v-tooltip) Demo</h1>\n    <p>Using the v-tooltip directive:</p>\n    <button v-tooltip=\"tooltipMessage\" class=\"btn\">\n      Hover me (Directive)\n    </button>\n\n    <p>Using the VDropdown component:</p>\n    <VDropdown>\n      <button class=\"btn\">Click for Dropdown</button>\n      <template #popper>\n        <div class=\"dropdown-content\">\n          {{ dropdownContent }}\n          <button class=\"btn\">Action 1</button>\n          <button class=\"btn\">Action 2</button>\n        </div>\n      </template>\n    </VDropdown>\n  </main>\n</template>\n\n<style>\nbody { font-family: sans-serif; margin: 20px; }\n.container { display: flex; flex-direction: column; gap: 20px; align-items: flex-start; }\n.btn { padding: 8px 15px; border: 1px solid #ccc; border-radius: 4px; background-color: #f0f0f0; cursor: pointer; }\n.dropdown-content { padding: 10px; background: white; border: 1px solid #eee; border-radius: 4px; box-shadow: 0 2px 8px rgba(0,0,0,0.15); display: flex; flex-direction: column; gap: 5px; }\n</style>\n\n<!-- main.ts or main.js -->\n<script type=\"module\">\nimport { createApp } from 'vue';\nimport App from './App.vue';\nimport FloatingVue from 'floating-vue';\nimport 'floating-vue/dist/style.css';\n\nconst app = createApp(App);\napp.use(FloatingVue);\napp.mount('#app');\n</script>","lang":"typescript","description":"This quickstart demonstrates both the `v-tooltip` directive and the `VDropdown` component from Floating Vue in a Vue 3 `script setup` environment, including global registration and CSS import."},"warnings":[{"fix":"For Vue 2 projects, continue using `floating-vue` v1 (which corresponds to `v-tooltip` v3/v4) or `v-tooltip` v2. For Vue 3 projects, install `v-tooltip` v5.x and migrate according to the `floating-vue` v2 migration guide, paying attention to the package rename and API changes.","message":"The `v-tooltip` package underwent a major rebranding and refactor in version 5.0.0. It is now essentially `floating-vue` v2.0.0, and primarily supports Vue 3. Previous versions (v2, v3, v4 of `v-tooltip`) were for Vue 2. Directly upgrading from `v-tooltip` v4 or earlier to v5 will cause breaking changes due to Vue version incompatibility and API changes.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Update all import statements from `v-tooltip` to `floating-vue`. For example, `import { VTooltip } from 'v-tooltip'` should become `import { VTooltip } from 'floating-vue'`.","message":"The package name for imports has changed from `v-tooltip` to `floating-vue` in v5.0.0, even though the npm package name remains `v-tooltip`. This can lead to import errors if not updated.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Review your component usage for `modifiers` and `offset` props. Replace `modifiers` with the new individual props, and refactor `offset` to use `distance` and `skidding` separately. Consult the migration guide for specific property mappings.","message":"In `floating-vue` (and thus `v-tooltip` v5), the positioning library changed from `Popper.js` 2 to `Floating UI`. This replaced the `modifiers` prop with new dedicated props like `preventOverflow`, `overflowPadding`, `shiftCrossAxis`, and `flip`. The `offset` prop also changed from an array `[skidding, distance]` to separate `distance` and `skidding` props.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Prefer using the `v-tooltip` and `v-close-popper` directives where possible. For complex popovers, `VDropdown` and `VMenu` components are still the recommended approach.","message":"The components `VTooltip` and `VClosePopper` (when used as components) received deprecation notices in `v5.2.1` in favor of their directive counterparts, `v-tooltip` and `v-close-popper`, especially for `script setup` usage.","severity":"deprecated","affected_versions":">=5.2.1"},{"fix":"Ensure you import the default stylesheet: `import 'floating-vue/dist/style.css';` in your main application entry file (e.g., `main.ts` or `main.js`).","message":"Default CSS styles are not automatically included with the plugin installation. If you don't import the default styles, tooltips and popovers will appear unstyled.","severity":"gotcha","affected_versions":">=5.0.0"},{"fix":"Globally disable HTML parsing for tooltips by setting `defaultHtml: false` in the plugin options: `app.use(FloatingVue, { defaultHtml: false })`. You can then re-enable HTML for specific tooltips with `v-tooltip=\"{ content: '...', html: true }\"` if strictly necessary and after proper sanitization.","message":"By default, HTML content is enabled in tooltips. If your tooltip content comes from user input, this can introduce Cross-Site Scripting (XSS) vulnerabilities.","severity":"gotcha","affected_versions":">=5.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure that Floating Vue components are rendered client-side only during SSR, or integrate with your SSR framework (e.g., Nuxt) to handle DOM-dependent code. For Vue, wrap the component in `<ClientOnly>` or dynamically import it on the client. Upgrading to the latest v5.x might also resolve some edge cases.","cause":"This error typically occurs when Floating Vue components or directives are used in a server-side rendering (SSR) environment without proper client-only rendering or SSR awareness. `floating-vue` v5.0.1 specifically fixed an issue related to this.","error":"ReferenceError: Element is not defined"},{"fix":"If using globally, ensure `import FloatingVue from 'floating-vue'; app.use(FloatingVue);` is present in your app entry. If importing locally for `script setup`, ensure `import { VTooltip } from 'floating-vue';` is used in the component script. Remember the package name for import is `floating-vue`.","cause":"This warning indicates that the `VTooltip` component (or `VDropdown`, `VMenu`) is not globally registered or correctly imported for local use. This often happens if `app.use(FloatingVue)` is missed or if the import path is incorrect.","error":"[Vue warn]: Failed to resolve component: VTooltip"},{"fix":"Ensure `import { options } from 'floating-vue';` is at the top of your configuration file and that any modifications to `options` happen after `app.use(FloatingVue)` if you're modifying them post-installation.","cause":"This error usually occurs when attempting to configure global `options.themes` or other global options without correctly importing `options` from the `floating-vue` package or before the plugin has been installed.","error":"TypeError: Cannot read properties of undefined (reading 'themes')"}],"ecosystem":"npm"}