Tooltip

Storybook Figma

A tooltip is a floating label that briefly explains an action, function, or an element. Its content is exclusively text and shouldn't be vital information for users. If richer media is desired, consider using a popover instead.

Preview

Tooltip as a Directive

Usage

Default

Default tooltip directive uses top as default placement

With Placement

It's possible to change the tooltip default placement with directive arguments, possible values: bottom, bottom-start, bottom-end, right, right-start, right-end, left, left-start, left-end, top, top-start, top-end.

<dt-button v-dt-tooltip:bottom-start="`Tooltip text`">Placeholder Button</dt-button>

With Object Syntax

It's possible to change any property of the tooltip with object syntax.

<dt-button v-dt-tooltip="{ message: 'Tooltip text', placement: 'bottom-start', delay: false }">Placeholder Button</dt-button>

Import

Import the directive from dialtone-vue

import { DtTooltipDirective } from "@dialpad/dialtone-vue";

Install the directive into vue instance

Vue.use(DtTooltipDirective);

Tooltip as a Component

The tooltip, also known as infotip or hint, is a common graphical user interface element in which, when hovering over a screen element or component, a text box displays information about that element (such as a description of a button's function, or what an abbreviation stands for). The tooltip is displayed continuously as long as the user hovers over the element.

When placing DtTooltip on a disabled DtButton, wrap the button in a <span> element — disabled elements do not fire mouse events, so the tooltip anchor must be on the wrapper, not on the disabled button itself.

A tooltip has two slots:

  1. the anchor required slot
  2. the default slot (which could be replaced with prop message)

Base Styles

Inverted

Placement

External anchor

Fallback Placements

The tooltip uses headless-tippy and popper, if the tooltip opens in a placement where it will be clipped, it will move to a new position. It will do this automatically by default, but if you want to manually specify which position it will move to in what order you can do so via the fallbackPlacements prop.

Vue API

Slots

Name
Description
anchor

Slot for the anchor element
default

Slot for the content, defaults to message prop

Props

Name
Description
Default
appendTo

Sets the element to which the tooltip is going to append to. 'body' will append to the nearest body (supports shadow DOM). This prop is not reactive, must be set on initial render.

 Type: HTML_ELEMENT_TYPE|string
Values: 'body''parent'HTMLElement
 'body'
contentClass

Additional css classes for the tooltip content element. Can accept all of: String, Object, and Array, i.e. has the same api as Vue's built-in handling of the class attribute.

 Type: string|object|array
''
delay

Whether the tooltip will have a delay when being focused or moused over.

 Type: boolean
Values: truefalse
 true
enabled

Controls whether hover/focus causes the tooltip to appear. Cannot be combined with the show prop. show value will be ignored. by default this is true, if you override with false, the tooltip will never show up.

 Type: boolean
true
externalAnchor

External anchor id to use in those cases the anchor can't be provided via the slot. For instance, using the combobox's input as the anchor for the popover.

 Type: string
null
externalAnchorElement

External anchor element reference. Use this instead of externalAnchor when the anchor may be inside a Shadow DOM, as querySelector cannot pierce shadow boundaries.

 Type: HTML_ELEMENT_TYPE
null
fallbackPlacements

If the popover does not fit in the direction described by "placement", it will attempt to change its direction to the "fallbackPlacements" if defined, otherwise it will automatically position to a new location as it sees best fit. See Popper.js docs

Type: array
['auto']
id

The id of the tooltip

 Type: string
function() { return getUniqueString(); }
inverted

If true, applies inverted styles to the tooltip

 Type: boolean
Values: truefalse
 false
message

A provided message for the tooltip content

 Type: string
''
offset

Displaces the tooltip from its reference element by the specified number of pixels. See Tippy.js docs

Type: array
[0, 12]
placement

The direction the popover displays relative to the anchor. See Tippy.js docs

Type: string
Values: toptop-starttop-endrightright-startright-endleftleft-startleft-endbottombottom-startbottom-endautoauto-startauto-end
 'top'
show

Controls whether the tooltip is shown. Leaving this null will have the tooltip trigger on mouseover by default. If you set this value, the default mouseover behavior will be disabled and you can control it as you need. Supports .sync modifier

 Type: boolean
Values: nulltruefalse
 null
sticky

If the tooltip sticks to the anchor. This is usually not needed, but can be needed if the reference element's position is animating, or to automatically update the popover position in those cases the DOM layout changes the reference element's position. true enables it, reference only checks the "reference" rect for changes and popper only checks the "popper" rect for changes. See Tippy.js docs

Type: boolean|string
Values: truefalsereferencepopper
 true
theme

Set a custom theme on the tooltip. See https://atomiks.github.io/tippyjs/v6/themes/

 Type: string
null
transition

Whether the tooltip should have a transition effect (fade).

 Type: boolean
true

Events

Name
Description
shown

Emitted when tooltip is shown or hidden

 Type: Boolean
update:show

Sync show value

 Type: undefined

Classes

Class
Applies to
Description

Accessibility

Reads out the tooltip content as a supplementary description for its trigger when the trigger is focused. See also wai aria practices 1.1.

Anchor

The anchor element that activates the tooltip should be fully accessible by keyboard. The easiest way to do this is by using an element like an DtButton that is already accessible. When pressing the ESC key in a focused tooltip, tooltip will be closed.

There are some required ARIA attributes for the anchor element (such as aria-hidden set based on open). To make this as straightforward as possible, these ARIA attributes are passed with the correct values as the attrs to the anchor slot. Applying them is as simple as using v-bind.

Focus & Keyboard

Due to the different contexts in which a tooltip can be used, focus management and keyboard shortcut ESC is provided. You are encouraged to consult the ARIA documentation for the particular role.

Item
Applies to
Description
Tooltip documentation last updated Thursday, June 11, 2026