---
title: "vTooltip"
description: "vTooltip is a Vue directive to display a text when the user hovers an element"
package: "maz-ui"
url: "https://maz-ui.com/directives/tooltip"
---

# vTooltip

> vTooltip is a Vue directive to display a text when the user hovers an element

- Package: `maz-ui`
- Import: `import { vTooltip } from 'maz-ui/directives/vTooltip'`
- Web: https://maz-ui.com/directives/tooltip

## Basic usage

```vue
<script lang="ts" setup>
import { vTooltip } from 'maz-ui/directives'
</script>

<template>
  <MazBtn v-tooltip="'This is a top tooltip'">
    Top
  </MazBtn>
  <MazBtn v-tooltip.right="'This is a top tooltip'">
    Right
  </MazBtn>
  <MazBtn v-tooltip.left="'This is a top tooltip'">
    Left
  </MazBtn>
  <MazBtn v-tooltip.bottom="'This is a top tooltip'">
    Bottom
  </MazBtn>
</template>
```

## Colors

```html
<MazBtn v-tooltip="{ text: 'Tooltip text', color: 'primary' }">
  Primary
</MazBtn>

<MazBtn v-tooltip="{ text: 'Tooltip text', color: 'secondary' }" color="secondary">
  Secondary
</MazBtn>

<MazBtn v-tooltip="{ text: 'Tooltip text', color: 'success' }" color="success">
  Success
</MazBtn>

<MazBtn v-tooltip="{ text: 'Tooltip text', color: 'warning' }" color="warning">
  Warning
</MazBtn>

<MazBtn v-tooltip="{ text: 'Tooltip text', color: 'destructive' }" color="destructive">
  destructive
</MazBtn>

<MazBtn v-tooltip="{ text: 'Tooltip text', color: 'info' }" color="info">
  Info
</MazBtn>

<MazBtn v-tooltip="{ text: 'Tooltip text', color: 'accent' }" color="accent">
  Accent
</MazBtn>

<MazBtn v-tooltip="{ text: 'Tooltip text', color: 'contrast' }" color="contrast">
  Contrast
</MazBtn>

<MazBtn v-tooltip="{ text: 'Tooltip text', color: 'default' }" color="surface">
  Background
</MazBtn>
```

## Position

You can change the position of the tooltip by passing a `position` option or using the directive modifier (e.g. `v-tooltip.top`).

```html
<MazBtn v-tooltip.bottom="{ text: 'Tooltip text' }">
  Bottom
</MazBtn>

<MazBtn v-tooltip.left="{ text: 'Tooltip text' }">
  Left
</MazBtn>

<MazBtn v-tooltip.right="{ text: 'Tooltip text' }">
  Right
</MazBtn>

<MazBtn v-tooltip.top="{ text: 'Tooltip text' }">
  Top
</MazBtn>

<MazBtn v-tooltip.top-start="{ text: 'Tooltip text' }">
  Top start
</MazBtn>

<MazBtn v-tooltip.top-end="{ text: 'Tooltip text' }">
  Top end
</MazBtn>

<MazBtn v-tooltip.bottom-start="{ text: 'Tooltip text' }">
  Bottom start
</MazBtn>

<MazBtn v-tooltip.bottom-end="{ text: 'Tooltip text' }">
  Bottom end
</MazBtn>
```

## HTML content

You can also use HTML content in the tooltip by passing a string to the `html` option.

```html
<MazBtn v-tooltip="{ html: '<strong>Tooltip</strong> text <br> with <br> line breaks' }">
  HTML
</MazBtn>
```

## Customization

You can customize the tooltip by passing a `panelClass` or `panelStyle` option.

```html
<MazBtn v-tooltip="{ text: 'Custom panel class', panelClass: 'text-red-500!' }">
  panelClass
</MazBtn>
<MazBtn v-tooltip="{ text: 'Custom panel style', panelStyle: 'background-color: red; color: white;' }">
  panelStyle
</MazBtn>
```

## Trigger

You can change the trigger mode of the tooltip by passing a `trigger` option.

The default trigger is `hover`.

The `adaptive` trigger will use the `click` trigger on touch devices (mobile and tablet) and the `hover` trigger on non-touch devices (desktop).

```html
<MazBtn v-tooltip="{ text: 'Tooltip text', trigger: 'click' }">
  Click
</MazBtn>

<MazBtn v-tooltip="{ text: 'Tooltip text', trigger: 'hover' }">
  Hover
</MazBtn>

<MazBtn v-tooltip="{ text: 'Tooltip text', trigger: 'adaptive' }">
  Adaptive
</MazBtn>
```

## Offset

The `offset` (in px) option allows you to adjust the position of the tooltip relative to the original element.

```html
<MazBtn v-tooltip="{ text: 'Tooltip text', offset: 0 }">
  0
</MazBtn>

<MazBtn v-tooltip="{ text: 'Tooltip text', offset: 10 }">
  10
</MazBtn>

<MazBtn v-tooltip="{ text: 'Tooltip text', offset: 20 }">
  20
</MazBtn>

<MazBtn v-tooltip="{ text: 'Tooltip text', offset: 40 }">
  40
</MazBtn>
```

## Open programmatically

```vue
<script lang="ts" setup>
  import { vTooltip } from 'maz-ui/directives'
  import { ref } from 'vue'

  const open = ref(true)
</script>

<template>
  <MazBtn v-tooltip.top="{ text: 'Tooltip text', open: open }">
    Primary
  </MazBtn>
  <MazBtn color="secondary" @click="open = !open">
    Toggle tooltip
  </MazBtn>
</template>
```

## Conditionally disable

Pass `false`, `null` or `undefined` as the binding value to silently disable the tooltip - no popover instance is created, no listeners are attached, and no warning is logged. This is the recommended way to skip the tooltip on the fly without conditionally rendering two different elements:

```vue
<script lang="ts" setup>
import { vTooltip } from 'maz-ui/directives'
import { computed, ref } from 'vue'

const label = ref<string>('')
const tooltipBinding = computed(() => label.value ? { text: label.value } : false)
</script>

<template>
  <!-- When label is empty the directive becomes a no-op -->
  <MazBtn v-tooltip="tooltipBinding">
    Hover me
  </MazBtn>
</template>
```

If the binding switches back to a valid value later, the tooltip mounts as expected. Toggling the value off again destroys the existing popover instance.

## Global install

### Vue

```typescript
import { vTooltipInstall } from 'maz-ui/directives'
import { createApp } from 'vue'

const app = createApp(App)

// Options are optional
app.use(vTooltipInstall, {
  position: 'top',
  color: 'primary',
})

app.mount('#app')
```

### Nuxt

Please refer to the [Nuxt module documentation](../ecosystem/nuxt.md) for more information.

## Types

```ts
interface VTooltipOptions extends Partial<Omit<MazPopoverProps, 'modelValue'>> {
  /**
   * Text to display in the tooltip
   */
  text?: string
  /**
   * HTML content (alternative to text)
   */
  html?: string
  /**
   * Color variant of the tooltip
   * @default default
   */
  color?: MazPopoverProps['color']
  /**
   * Position of the tooltip
   * @default top
   */
  position?: PopoverPosition
  /**
   * Trigger of the tooltip
   * @default hover
   */
  trigger?: MazPopoverTrigger
  /**
   * Close on click outside
   * @default false
   */
  closeOnClickOutside?: boolean
  /**
   * Close on escape
   * @default false
   */
  closeOnEscape?: boolean

  /**
   * Open the tooltip
   * @default false
   */
  open?: boolean
}

type VTooltipBindingValue
  = | string
    | VTooltipOptions
```