Floating Vue

# API Reference

# Global

# hideAllPoppers

Hides all shown poppers.

import { hideAllPoppers } from 'floating-vue'

hideAllPoppers()

# createTooltip

createTooltip(el, valueOrOptions, directiveModifiers) creates a tooltip on a given element.

import { createTooltip, destroyTooltip } from 'floating-vue'

export function clipboardSuccess (el) {
  const tooltip = createTooltip(el, {
    triggers: [],
    content: 'Text copied!',
  })
  tooltip.show()
  setTimeout(() => {
    tooltip.hide()
    // Transition
    setTimeout(() => {
      destroyTooltip(el)
    }, 400)
  }, 600)
}

# destroyTooltip

destroyTooltip(el) destroys a tooltip on a given element.

See example above.

# Directive options

<button v-tooltip="{
  /* options */
}">

The directive also support all the Component props.

# content

HTML text to be displayed in the tooltip. Can also be a function that returns the content or a Promise.

<template>
  <button v-tooltip="{ content: 'Hello world' }">
    Hover me
  </button>
</template>

If you don't need any other option you can directly put the content in the directive:

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

Example with a function that returns a Promise:

<template>
  <button v-tooltip="{ content: fetchTooltip }">
    Hover me
  </button>
</template>

WARNING

Put the function, not a function call! That way the function is only called when the tooltip is shown.

Don't:

{ content: fetchTooltip() }

Do:

{ content: fetchTooltip }

# html

Boolean: allow HTML tooltip content.

<template>
  <button v-tooltip="{ content: '<i>Italic</i>', html: true }">
    Hover me
  </button>
</template>

# loadingContent

Same as content, used when the actual tooltip content is loading.

<template>
  <button
    v-tooltip="{
      content: fetchTooltip,
      loadingContent: 'Loading tooltip...',
    }"
  >
    Hover me
  </button>
</template>

# Component props

# theme

The popper theme applied to the popper (default: 'dropdown').

Learn more

# popperClass

Quick way to add one-time classes to the popper container, for example to limit its width in a specific situation.

TIP

It's recommended to use themes to style the poppers.

# placement

Popper placement (default: 'bottom').

The available placements are:

  • 'auto'
  • 'auto-start'
  • 'auto-end'
  • 'top'
  • 'top-start'
  • 'top-end'
  • 'right'
  • 'right-start'
  • 'right-end'
  • 'bottom'
  • 'bottom-start'
  • 'bottom-end'
  • 'left'
  • 'left-start'
  • 'left-end'

# strategy

Either absolute or fixed (default: absolute). If your reference element is in a fixed container, use the fixed strategy.

# triggers

Array of events triggering the popper.

Available events:

  • 'hover'
  • 'click'
  • 'focus'
  • 'touch'

Example:

<VDropdown :triggers="['hover', 'focus']"/>

If you want to manually trigger the popper, use an empty array: :triggers="[]":

<!-- Manual -->
<VDropdown :triggers="[]"/>

# showTriggers

Override the trigger events for showing.

Can also be a function that gets the triggers list, and should return the new list:

<VDropdown
  :showTriggers="triggers => [...triggers, 'click']"
/>

# hideTriggers

Override the trigger events for hiding.

Can also be a function that gets the triggers list, and should return the new list:

<VDropdown
  :hideTriggers="triggers => [...triggers, 'click']"
/>

# popperTriggers

Array of events triggering the popper applied on the popper container itself.

Available events:

  • 'hover'
  • 'click'
  • 'focus'
  • 'touch'

For example, it's useful when triggering on hover so that the popper stay open when mouse hovering it:

<VDropdown
  :popperTriggers="['hover']"
/>

# popperShowTriggers

Override the trigger events for showing on the popper container itself.

Can also be a function that gets the triggers list, and should return the new list:

<VDropdown
  :popperShowTriggers="triggers => [...triggers, 'click']"
/>

# popperHideTriggers

Override the trigger events for hiding on the popper container itself.

Can also be a function that gets the triggers list, and should return the new list:

<VDropdown
  :popperHideTriggers="triggers => [...triggers, 'click']"
/>

# delay

Show/Hide delay, or object in ms.

Examples:

<VDropdown :delay="200" />

<VDropdown :delay="{ show: 500, hide: 100 }" />

# shown

Boolean that shows or hide the popper. You should probably use no trigger events (manual mode).

<VDropdown :shown="isMenuShown" :triggers="[]" />

# distance

Distance along the main axis relative to the reference (pixels).

<VDropdown :distance="12" />

# skidding

Skidding along the cross axis relative to the reference (pixels).

<VDropdown :skidding="12" />

# arrowPadding

Padding of the arrow relative to the popper bounds to prevent it from overflowing if you have rounded borders on the popper (pixels).

<VDropdown :arrow-padding="12" />

Learn more

# container

Selector: Container where the popper will be appended (e.g. 'body').

# boundary

DOM element for the popper position and size boundaries.

# autoHide

Hide the popper if clicked outside.

<VDropdown auto-hide />

# disabled

Boolean that disables the popper. If it was already open, it will be closed.

# positioningDisabled

Boolean that disables the automatic positioning of the popper. You can then style it manually. Useful for mobile version of the popper.

# handleResize

Boolean: Automatically update the popper position if its size changes.

<VDropdown handle-resize />

# showGroup

If set, will close all the open popovers that have a different or unset showGroup value.

<VDropdown show-group="my-group-name" />

# instantMove

Boolean: skip delay & CSS transitions when another popper is open, so that the popper appear to instanly move to the new position.

<VDropdown instant-move />

# eagerMount

Boolean: mount the popper content without waiting for the popper to be displayed.

<VDropdown eager-mount />

# disposeTimeout

Number of ms after hide when the popper instance is destroyed.

# computeTransformOrigin

Computes the transform origin of the .v-popper__wrapper to allow zooming effects relative to the reference element.

Example:

<template>
  <VDropdown compute-transform-origin />
</template>

<style>
.v-popper__wrapper {
  transition: transform .15s;
}

.v-popper__popper.v-popper__popper--hidden .v-popper__wrapper {
  transform: scale(.5);
}
</style>

Live example

# autoSize

Boolean | 'min' | 'max': set the size of the popper inner container depending on the size of the reference.

  • If the final placement is top-* or bottom-*, the reference width will be taken into account.
  • If the final placement is left-* or right-*, the reference height wll be taken into account.

Possible values:

  • true: the popper container will be set to the same size as the reference element.
  • 'min': the popper container will be set to the minimum size of the reference element.
  • 'max': the popper container will be set to the maximum size of the reference element.
<VDropdown auto-size />
<VDropdown auto-size="min" />
<VDropdown auto-size="max" />

# autoBoundaryMaxSize

Boolean: let floating vue resize the popper inner container to the available size (using max-width and max-height). It's very useful for a dropdown that should automatically shrink its size when it reaches the boundary.

<VDropdown auto-boundary-max-size />

# preventOverflow

Boolean: prevent the popper from overflowing the boundary.

<VDropdown :prevent-overflow="false" />

# overflowPadding

Virtual padding in the boundary used to prevent the popper overflow (pixels).

<VDropdown :overflow-padding="10" />

# flip

Boolean: prevent the popper from overflowing the boundary by using an opposite placement if needed.

<VDropdown :flip="false" />

# shift

Boolean: prevent the popper from overflowing the boundary by adjusting its position.

<VDropdown :shift="false" />

# shiftCrossAxis

Boolean: prevent the popper from overflowing the boundary by adjusting its position.

<VDropdown shift-cross-axis />

# noAutoFocus

Boolean: disable the auto focus on the popper DOM node when shown.

<VDropdown no-auto-focus />

# ariaId

Id used for the aria-describedby attribute. By default a random id.

# Component slots

# default

Content put in the trigger part of the popper, typically a button.

  • Props:
    • shown: boolean indicating if the popper is shown
    • show: method to show the popper
    • hide: method to hide the popper
<VDropdown>
  <button>Click me</button>
</VDropdown>

# popper

Content put inside the popper of the popper.

  • Props:
    • shown: boolean indicating if the popper is shown
    • hide: method to hide the popper
<VDropdown>
  <button>Click me</button>

  <template #popper="{ hide }">
    Menu content here!
    <button @click="hide()">Close</button>
  </template>
</VDropdown>

# Component events

# update:shown

Boolean: This allow you to use the .sync modifier on the show prop (Vue 2) or the v-model:shown directive (Vue 3).

<!-- Vue 3 -->
<VDropdown v-model:shown="isMenuShown" />

<!-- Vue 2 -->
<VDropdown :shown.sync="isMenuShown" />

# show

When the popper is going to be shown.

# apply-show

Emitted after the show delay.

# hide

When the popper is going to be hidden.

# apply-hide

Emitted after the hide delay.

# dispose

Popper instance is destroyed.

# auto-hide

Emitted when the popper is closed if clicked outside.

# close-directive

Emitted when the popper is closed with the Close directive.

# close-group

Emitted when the popper is closed because a popper of another showGroup was shown.

# resize

Emitted when the content size changes. You must set the handleResize prop to true.

# Close directive

Use the v-close-popper directive on an element inside the dropdown to close it when the element is clicked (or touched on mobile):

<VDropdown>
  <button>Click me</button>

  <template #popper>
    <a v-close-popper>Close</a>
  </template>
</VDropdown>

Value: Boolean (default: true). Pass false to disable the directive.

Modifiers:

  • all: Close all the poppers in the page.