Floating Vue

Floating Vue is a library for creating tooltips, dropdowns, and menus in Vue applications. It is built on top of Floating UI.

Note that the package was previously named v-tooltip. It supports both Vue 2 and Vue 3 via different major versions.

To install the necessary dependencies for the demo2 project, run the following command in your terminal:

yarn install

The v-tooltip directive allows you to add tooltips to elements. It supports all component props.

Basic Usage

Pass a string directly for simple text:

<button v-tooltip="'Hello world'">Hover me</button>

Advanced Options

Pass an object to configure behavior:

• content: The text or a function/Promise returning content. Note: Pass the function reference, not the result of the call (e.g., { content: fetchTooltip }, not { content: fetchTooltip() }).
• html: Boolean to allow HTML content.
• loadingContent: Content to show while the main content is loading.

<template>
  <!-- Using an object with HTML and loading state -->
  <button v-tooltip="{ content: fetchTooltip, loadingContent: 'Loading...', html: true }">
    Hover me
  </button>
</template>

To organize your code, you can create a reusable component that uses a specific theme by extending the PopperWrapper component and setting the vPopperTheme option.

<script>
import { PopperWrapper } from 'floating-vue'

export default {
  ...PopperWrapper,
  name: 'VInfoDropdown',
  vPopperTheme: 'info-dropdown',
}
</script>

<style>
/* Scoped or global styles for the theme */
.v-popper--theme-info-dropdown .v-popper__inner {
  background: #004499;
}

.v-popper--theme-info-dropdown .v-popper__arrow-inner {
  border-color: #004499;
}
</style>

<!-- Usage -->
<VInfoDropdown>
  <button>My customized dropdown</button>

  <template #popper>
    Hello world
  </template>
</VInfoDropdown>

If you are upgrading from v-tooltip to floating-vue, note the following package mapping and compatibility:

Key architectural changes include the transition from popperjs 2 to floating-ui for positioning.

The VMenu component uses the menu theme, which extends the dropdown theme. It is specifically configured for mouse-over interactions by overriding triggers and delay.

<VMenu>
  <button>Documentation</button>

  <template #popper>
    <button>Guide</button>
    <button>API Reference</button>
  </template>
</VMenu>

You can set default values for all available props globally so they don't need to be specified on every popper directive or component.

There are two ways to apply configuration:

1. During Vue installation: Pass an options object as the second argument to Vue.use().
2. Directly on the FloatingVue object: Modify the FloatingVue.options property.

// Option 1: During installation
import FloatingVue from 'floating-vue'
Vue.use(FloatingVue, options)

// Option 2: Directly on the FloatingVue object
import FloatingVue from 'floating-vue'
FloatingVue.options.distance = 12

When a popper is visible, the target element (the element triggering the popper) automatically receives the data-popper-shown attribute. You can use this attribute in CSS to style the trigger element based on the popper's visibility.

Example: Change button background when tooltip is shown

button[data-popper-shown] {
  background: #f00;
}

For Vue 2 projects, use the vue2 NPM tag.

Install the package:

npm i floating-vue@vue2
# or
yarn add floating-vue@vue2
# or
pnpm add floating-vue@vue2

Register the plugin or components using the Vue 2 API:

import Vue from 'vue'
import FloatingVue from 'floating-vue'
import 'floating-vue/dist/style.css'

// As a plugin
Vue.use(FloatingVue)

// Or manually
import {
  vTooltip,
  vClosePopper,
  Dropdown,
  Tooltip,
  Menu
} from 'floating-vue'

Vue.directive('tooltip', vTooltip)
Vue.directive('close-popper', vClosePopper)
Vue.component('VDropdown', Dropdown)
Vue.component('VTooltip', Tooltip)
Vue.component('VMenu', Menu)

To execute the end-to-end test suite, run the following command:

yarn test:e2e

Use the VTooltip component when you need to display tooltips containing components or more advanced content. It uses the tooltip theme.

<VTooltip>
  <a>Sponsor me</a>

  <template #popper>
    Help me fund my Open Source work!
  </template>
</VTooltip>