vTooltip

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

Basic usage

Hover the buttons

<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

Hover the buttons

<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).

<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.

<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.

<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).

<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.

<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

<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:

<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

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 for more information.

Types

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