{"id":10904,"library":"floating-vue","title":"Floating Vue Components","description":"floating-vue is a Vue.js library for creating interactive floating UI elements such as tooltips, dropdowns, menus, and popovers. It is built upon the robust Floating UI library for precise and efficient positioning. The current stable version is 5.2.2, with active maintenance demonstrated by frequent patch and minor releases. A key differentiator is its comprehensive integration with Vue 3, providing both components (like VTooltip, VDropdown) and directives (like v-tooltip, v-close-popper) for declarative control over floating elements. The library ships with full TypeScript type definitions, enhancing developer experience and project reliability. It also offers powerful theming capabilities and flexible configuration options to adapt to various design systems.","status":"active","version":"5.2.2","language":"javascript","source_language":"en","source_url":"https://github.com/Akryum/floating-vue","tags":["javascript","vue","popper","tooltip","popover","dropdown","menu","typescript"],"install":[{"cmd":"npm install floating-vue","lang":"bash","label":"npm"},{"cmd":"yarn add floating-vue","lang":"bash","label":"yarn"},{"cmd":"pnpm add floating-vue","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for Vue.js applications.","package":"vue","optional":false},{"reason":"Peer dependency for Nuxt.js applications, providing Nuxt 3 integration.","package":"@nuxt/kit","optional":true}],"imports":[{"note":"Used for global plugin installation via `app.use(FloatingVue)`. Also requires `import 'floating-vue/dist/style.css'`.","wrong":"const FloatingVue = require('floating-vue'); // CommonJS is not the primary import style for this ESM-first library","symbol":"FloatingVue","correct":"import FloatingVue from 'floating-vue'"},{"note":"The VTooltip component is the primary way to create tooltips. While a `v-tooltip` directive exists, the component is recommended for complex content.","wrong":"import VTooltip from 'floating-vue/src/components/VTooltip'; // Incorrect path, use direct named import from root","symbol":"VTooltip","correct":"import { VTooltip } from 'floating-vue'"},{"note":"Used for creating dropdowns and menus. The content for the dropdown should be passed via the `#popper` slot.","wrong":"import { Dropdown } from 'floating-vue'; // 'Dropdown' is often confused, it's 'VDropdown'","symbol":"VDropdown","correct":"import { VDropdown } from 'floating-vue'"},{"note":"Directive to close a popper. Can be used on elements inside the popper's content.","symbol":"v-close-popper","correct":"<button v-close-popper>Close</button>"},{"note":"A global helper function to manually recompute the position of all currently shown poppers, useful for dynamic content changes.","wrong":"import FloatingVue, { recomputeAllPoppers } from 'floating-vue'; // recomputeAllPoppers is a separate utility import","symbol":"recomputeAllPoppers","correct":"import { recomputeAllPoppers } from 'floating-vue'"}],"quickstart":{"code":"import { createApp, ref } from 'vue';\nimport FloatingVue from 'floating-vue';\nimport 'floating-vue/dist/style.css';\n\nconst App = {\n  setup() {\n    const message = ref('Hello Floating Vue!');\n    const count = ref(0);\n\n    setInterval(() => {\n      count.value++;\n    }, 2000);\n\n    const dynamicContent = `You have <b>${count.value}</b> new messages.`;\n\n    return {\n      message,\n      count,\n      dynamicContent\n    };\n  },\n  template: `\n    <div id=\"app\" class=\"p-8 flex flex-col items-center space-y-4\">\n      <h1 class=\"text-2xl font-bold\">Floating Vue Basic Example</h1>\n\n      <VTooltip :distance=\"10\">\n        <button class=\"px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600\">Hover for Tooltip (Static)</button>\n        <template #popper>\n          <div class=\"p-2 bg-gray-700 text-white rounded shadow-lg\">\n            {{ message }}\n          </div>\n        </template>\n      </VTooltip>\n\n      <VTooltip placement=\"right\" :distance=\"10\">\n        <button class=\"px-4 py-2 bg-green-500 text-white rounded hover:bg-green-600\">Hover for Tooltip (Dynamic)</button>\n        <template #popper>\n          <div class=\"p-2 bg-gray-700 text-white rounded shadow-lg\" v-html=\"dynamicContent\"></div>\n        </template>\n      </VTooltip>\n\n      <VDropdown :distance=\"10\">\n        <button class=\"px-4 py-2 bg-purple-500 text-white rounded hover:bg-purple-600\">Click for Dropdown</button>\n        <template #popper>\n          <div class=\"p-4 bg-white rounded shadow-lg border\">\n            <p class=\"mb-2\">Dropdown Content</p>\n            <button v-close-popper class=\"px-3 py-1 bg-red-500 text-white rounded hover:bg-red-600\">Close Me</button>\n          </div>\n        </template>\n      </VDropdown>\n    </div>\n  `,\n};\n\nconst app = createApp(App);\napp.use(FloatingVue);\napp.mount('#app');\n","lang":"typescript","description":"This quickstart demonstrates the installation of Floating Vue, its styling, and the usage of basic `VTooltip` (static and dynamic content) and `VDropdown` components with the `v-close-popper` directive."},"warnings":[{"fix":"Review the full changelog and migration guides carefully if upgrading from `v-tooltip` versions 3 or 4, or `floating-vue` v1, as many internal APIs, prop names, and CSS classes were changed or renamed.","message":"Version 5.0.0 was a re-bump of v2.0.0, primarily to resolve NPM tag issues, and officially announced 'no changes' compared to v2.0.0. However, the internal versioning history can be confusing, as subsequent patches like v5.0.3 introduced changes like `disposeTimeout` default values.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Explicitly set `disposeTimeout={0}` (or your desired duration) on `VTooltip`, `VDropdown`, or in global options if you require immediate DOM removal or a specific delay.","message":"The default value of the `disposeTimeout` prop, which controls how long a popper instance persists after hiding, was changed in v5.0.3 from 0ms to the default transition duration. This could cause unexpected behavior where poppers remain in the DOM longer than anticipated.","severity":"breaking","affected_versions":">=5.0.3"},{"fix":"Consult the official Floating Vue documentation or GitHub issues for the most up-to-date guidance on `VTooltip` and `VClosePopper` usage. Be prepared for potential API changes in future major versions. Consider component-based approaches for complex scenarios.","message":"A deprecation notice for `VTooltip` and `VClosePopper` was added in v5.2.1. While the components and directives are still functional and present in the documentation, it indicates a potential future shift in recommended usage or API structure.","severity":"deprecated","affected_versions":">=5.2.1"},{"fix":"For versions `v5.2.1` and newer, use the `autoHideOnMousedown` configuration option if you experience issues with poppers closing prematurely on mouse clicks. Check the global configuration for `autoHide` settings.","message":"The `autohide` behavior, specifically on `mousedown` events, was altered and then reverted/made configurable in v5.2.1. Previously, `mousedown` might unexpectedly close poppers, which was then addressed by introducing `autoHideOnMousedown` in config.","severity":"breaking","affected_versions":">=5.1.0 <=5.2.0"},{"fix":"Refer to the specific migration guides on the Floating Vue documentation website (e.g., 'Migration from v-tooltip 2', 'Migration from v-tooltip 3 & 4') when upgrading from older `v-tooltip` versions.","message":"The package moved from `v-tooltip` to `floating-vue` and changed its underlying positioning library from `Popper.js` to `Floating UI`. This involved significant breaking changes in prop names, global configuration, CSS classes (now BEM-like with `v-popper` prefix), and the modifier API.","severity":"gotcha","affected_versions":"all versions if migrating from `v-tooltip`"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you have `import FloatingVue from 'floating-vue'` and `import 'floating-vue/dist/style.css'` in your main application file, followed by `app.use(FloatingVue)` after creating your Vue app instance.","cause":"The `FloatingVue` plugin or its styles have not been correctly imported and registered in the Vue application entry point.","error":"`FloatingVue` is not defined or `app.use` expects a plugin with an install method."},{"fix":"If using a build setup, ensure `app.use(FloatingVue)` is called once. If using components directly in a SFC, `import { VTooltip } from 'floating-vue'` and add it to the `components` option, or use `<script setup>` for auto-import.","cause":"The `VTooltip` (or other Floating Vue components) component is not globally registered, or not imported in the local component where it's being used.","error":"[Vue warn]: Failed to resolve component: VTooltip (or VDropdown, VMenu)"},{"fix":"Wrap Floating Vue components in a `<ClientOnly>` component if you are using Nuxt or similar SSR frameworks, or dynamically import them to ensure they only render on the client side. A fix for a specific instance of this was released in v5.0.1.","cause":"Floating Vue components or directives might try to access browser-specific `window` or `document` objects during server-side rendering, leading to errors.","error":"`Element` is not defined on server (or similar SSR errors)"},{"fix":"Introduce a small delay (e.g., `nextTick` or a short `setTimeout`) between setting `shown = false` and `shown = true`, or when re-assigning a new target for the popper, to allow the internal closing/opening logic to complete. Consider using `recomputeAllPoppers()` after dynamic changes if issues persist.","cause":"Rapidly toggling the `shown` prop or switching targets without an adequate delay can sometimes prevent the popper from correctly re-initializing or closing/opening, especially if `disposeTimeout` is active or internal state transitions overlap.","error":"Dropdown/Tooltip closes immediately or fails to open reliably when rapidly changing its `shown` prop or target."}],"ecosystem":"npm"}