Tooltip

Tooltips appear on demand to explain UI elements, clarify functionality, or provide helpful context without permanently occupying screen space. They automatically position themselves relative to their trigger element.

import {TooltipModule} from "@qualcomm-ui/angular/tooltip"

Overview

The tooltip should be used to provide additional non-essential information. It is linked to an interactive element (the trigger) and will be shown when this element is focused or hovered. Because the tooltip itself can't be focused or tabbed to, it should not contain interactive elements. Only one tooltip can be open at a time.

In general, tooltips should be used sparingly and only contain succinct information. Here are guidelines to help you decide when to use one:

When using controls that lack visual labels, like icon buttons.
When defining a term or inline item.
When additional information may help a user make decisions.
When providing more context to an element.

Examples

Simple

The simple API provides a standalone component with built-in layout. The trigger is supplied as a child directive, and the content of the tooltip is the children.

<div q-tooltip>
  <button emphasis="primary" q-button q-tooltip-trigger variant="fill">
    Hover me
  </button>
  Hello World!
</div>

Composite

Build with the composite API for granular control. This API requires you to provide each subcomponent, but gives you full control over the structure and layout.

<div q-tooltip-root>
  <button emphasis="primary" q-button q-tooltip-trigger variant="fill">
    Hover me
  </button>
  <q-portal>
    <div q-tooltip-positioner>
      <div q-tooltip-content>
        <div q-tooltip-arrow>
          <div q-tooltip-arrow-tip></div>
        </div>
        Hello World!
      </div>
    </div>
  </q-portal>
</div>

Placement

The tooltip's position, relative to the trigger element, can be set using the placement option of the positioning prop. Its default value is top. Change the values in the example below and hover over the select to see the tooltip position change.

import {Component, signal} from "@angular/core"
import {FormsModule} from "@angular/forms"

import {PortalDirective} from "@qualcomm-ui/angular-core/portal"
import {SelectModule} from "@qualcomm-ui/angular/select"
import {TooltipModule} from "@qualcomm-ui/angular/tooltip"
import {selectCollection} from "@qualcomm-ui/core/select"
import type {Placement} from "@qualcomm-ui/dom/floating-ui"

@Component({
  imports: [TooltipModule, SelectModule, FormsModule, PortalDirective],
  selector: "tooltip-placement",
  template: `
    <div class="flex flex-col">
      <div q-tooltip-root [positioning]="{placement: placement()[0]}">
        <div
          class="w-48"
          q-select-root
          [collection]="collection()"
          [(ngModel)]="placement"
        >
          <div q-tooltip-trigger>
            <div aria-label="Select placement" q-select-control>
              <span q-select-value-text></span>
              <button q-select-indicator></button>
            </div>
          </div>
          <select q-select-hidden-select></select>
          <ng-template qPortal>
            <div q-select-positioner>
              <div q-select-content>
                <q-select-items />
              </div>
            </div>
          </ng-template>
        </div>
        <q-tooltip-floating-portal>
          {{ placement()[0] }}
        </q-tooltip-floating-portal>
      </div>
    </div>
  `,
})
export class TooltipPlacementDemo {
  readonly placement = signal<Placement[]>(["top"])

  readonly collection = signal(
    selectCollection({
      items: [
        "top-start",
        "top",
        "top-end",
        "right-start",
        "right",
        "right-end",
        "bottom-start",
        "bottom",
        "bottom-end",
        "left-start",
        "left",
        "left-end",
      ],
    }),
  )
}

Close On Click / Escape

By default, the tooltip will close when the Escape key is pressed or a click is detected. You can customize this behavior using the closeOnClick and closeOnEscape props.

<div closeOnClick="false" closeOnEscape="false" q-tooltip>
  <button emphasis="primary" q-button q-tooltip-trigger variant="fill">
    Hover me
  </button>
  Hello World!
</div>

Controlled Visibility

Use open and openChanged to control the component's visibility manually. These props follow our controlled state pattern.

the tooltip is closed

import {Component, signal} from "@angular/core"

import {ButtonModule} from "@qualcomm-ui/angular/button"
import {TooltipModule} from "@qualcomm-ui/angular/tooltip"

@Component({
  imports: [TooltipModule, ButtonModule],
  selector: "tooltip-controlled-state-demo",
  template: `
    <div class="flex flex-col items-center gap-4">
      <div q-tooltip [open]="open()" (openChanged)="handleOpenChange($event)">
        <button emphasis="primary" q-button q-tooltip-trigger variant="fill">
          Hover me
        </button>
        Hello World!
      </div>

      <output class="text-neutral-primary block">
        the tooltip is {{ open() ? "open" : "closed" }}
      </output>
    </div>
  `,
})
export class TooltipControlledStateDemo {
  readonly open = signal(false)

  handleOpenChange(open: boolean): void {
    this.open.set(open)
  }
}

Disabled

You can disable the tooltip by using the disabled prop.

<div q-tooltip [disabled]="disabled()">
  <button emphasis="primary" q-button q-tooltip-trigger variant="fill">
    Hover me
  </button>
  Hello World!
</div>

Shortcuts

A helper component that combines the portal, positioner, content, and arrow components. This shortcut is equivalent to:

<q-portal>
  <div q-tooltip-positioner>
    <div q-tooltip-content>
      <div q-tooltip-arrow>
        <div q-tooltip-arrow-tip></div>
      </div>
      <ng-content />
    </div>
  </div>
</q-portal>

API

The simple tooltip extends the q-tooltip-root directive with the following props:

Prop	Type
disablePortal If true, the tooltip will not be rendered in a DOM portal.	boolean
hideArrow Whether to hide the arrow.	boolean

disablePortal

Type

boolean

Description

If true, the tooltip will not be rendered in a DOM portal.

hideArrow

Type

boolean

Description

Whether to hide the arrow.

Composite API

Prop	Type
closeOnClick Whether the tooltip should close when the trigger is clicked.	boolean
closeOnEscape Whether to close the tooltip when the escape key is pressed.	boolean
dir The document's text/writing direction.	'ltr' \| 'rtl'
disabled The disabled state of the tooltip	boolean
id HTML id attribute. If omitted, a unique identifier will be generated for accessibility.)	string
open The open state of the tooltip.	boolean
positioning The user provided options used to position the popover content	TooltipPositioningOptions
(openChanged) Function called when the tooltip is opened/closed.	boolean

closeOnClick

Type

boolean

Description

Whether the tooltip should close when the trigger is clicked.

closeOnEscape

Type

boolean

Description

Whether to close the tooltip when the escape key is pressed.

dir

Type

'ltr' | 'rtl'

Description

The document's text/writing direction.

disabled

Type

boolean

Description

The disabled state of the tooltip

Type

string

Description

HTML id attribute. If omitted, a unique identifier will be generated for accessibility.)

open

Type

boolean

Description

The open state of the tooltip.

positioning

Type

TooltipPositioningOptions

Description

The user provided options used to position the popover content

(openChanged)

Type

boolean

Description

Function called when the tooltip is opened/closed.

q-tooltip-trigger

Prop	Type
id id attribute. If omitted, a unique identifier will be generated for accessibility.)	string

Type

string

Description

id attribute. If omitted, a unique identifier will be generated for accessibility.)

Attribute / Property	Value
`data-expanded`
`data-state`	\| 'open' \| 'closed'
`data-tooltip-part`	'trigger'

Prop	Type
id id attribute. If omitted, a unique identifier will be generated for accessibility.)	string

Type

string

Description

id attribute. If omitted, a unique identifier will be generated for accessibility.)

Attribute / Property	Value
`class`	'qui-tooltip__positioner'
`data-tooltip-part`	'positioner'
`style`	CSSProperties

Prop	Type
id id attribute. If omitted, a unique identifier will be generated for accessibility.)	string

Type

string

Description

id attribute. If omitted, a unique identifier will be generated for accessibility.)

Attribute / Property	Value
`class`	'qui-tooltip__content'
`data-placement`	\| 'bottom' \| 'bottom-end' \| 'bottom-start' \| 'left' \| 'left-end' \| 'left-start' \| 'right' \| 'right-end' \| 'right-start' \| 'top' \| 'top-end' \| 'top-start'
`data-state`	\| 'open' \| 'closed'
`data-tooltip-part`	'content'
`hidden`	boolean

class

Value

'qui-tooltip__content'

data-placement

Value

| 'bottom'
| 'bottom-end'
| 'bottom-start'
| 'left'
| 'left-end'
| 'left-start'
| 'right'
| 'right-end'
| 'right-start'
| 'top'
| 'top-end'
| 'top-start'

data-state

Value

| 'open'
| 'closed'

data-tooltip-part

Value

'content'

hidden

Value

boolean

Prop	Type
id id attribute. If omitted, a unique identifier will be generated for accessibility.)	string

Type

string

Description

id attribute. If omitted, a unique identifier will be generated for accessibility.)

Attribute / Property	Value
`class`	'qui-tooltip__arrow'
`data-tooltip-part`	'arrow'
`style`	CSSProperties

Attribute / Property	Value
`class`	'qui-tooltip__arrow-tip'
`data-tooltip-part`	'arrow-tip'
`style`	CSSProperties

Prop	Type	Default
arrowPadding The minimum padding between the arrow and the floating element's corner.	number	10
arrowSelector CSS selector used to locate the arrow element within the floating element. Components override this with their own anatomy-namespaced selector (e.g. `[data-menu-part=arrow]`).	string
boundary The overflow boundary of the reference element	() => \| 'clippingAncestors' \| Element \| Array<Element> \| { height: number width: number x: number y: number }
fitViewport Whether the popover should fit the viewport.	boolean
flip Whether to flip the placement when the floating element overflows the boundary.	\| boolean \| Array< \| 'bottom' \| 'bottom-end' \| 'bottom-start' \| 'left' \| 'left-end' \| 'left-start' \| 'right' \| 'right-end' \| 'right-start' \| 'top' \| 'top-end' \| 'top-start' >	true
getAnchorRect Function that returns the anchor rect	( element: \| HTMLElement \| VirtualElement, ) => { height?: number width?: number x?: number y?: number }
gutter The main axis offset or gap between the reference and floating element	number	8
hideWhenDetached Whether the popover should be hidden when the reference element is detached	boolean
listeners Options to activate auto-update listeners	\| boolean \| { ancestorResize?: boolean ancestorScroll?: boolean animationFrame?: boolean elementResize?: boolean layoutShift?: boolean }	true
offset The offset of the floating element	{ crossAxis?: number mainAxis?: number }
onComplete Function called when the placement is computed	( data: ComputePositionReturn, ) => void
onPositioned Function called when the floating element is positioned or not	(data: { placed: boolean }) => void
overflowPadding The virtual padding around the viewport edges to check for overflow	number
overlap Whether the floating element can overlap the reference element	boolean	false
placement The initial placement of the floating element	\| 'bottom' \| 'bottom-end' \| 'bottom-start' \| 'left' \| 'left-end' \| 'left-start' \| 'right' \| 'right-end' \| 'right-start' \| 'top' \| 'top-end' \| 'top-start'	'top'
sameWidth Whether to make the floating element same width as the reference element	boolean
shift The secondary axis offset or gap between the reference and floating elements	number
slide Whether the popover should slide when it overflows.	boolean
strategy The strategy to use for positioning	\| 'absolute' \| 'fixed'	'absolute'
updatePosition A callback that will be called when the popover needs to calculate its position.	(data: { updatePosition: () => Promise<void> }) => void \| Promise<void>

arrowPadding

Type

number

Description

The minimum padding between the arrow and the floating element's corner.

arrowSelector

Type

string

Description

CSS selector used to locate the arrow element within the floating element. Components override this with their own anatomy-namespaced selector (e.g. [data-menu-part=arrow]).

boundary

Type

() =>
| 'clippingAncestors'
| Element
| Array<Element>
| {
    height: number
    width: number
    x: number
    y: number
  }

Description

The overflow boundary of the reference element

fitViewport

Type

boolean

Description

Whether the popover should fit the viewport.

flip

Type

| boolean
| Array<
    | 'bottom'
    | 'bottom-end'
    | 'bottom-start'
    | 'left'
    | 'left-end'
    | 'left-start'
    | 'right'
    | 'right-end'
    | 'right-start'
    | 'top'
    | 'top-end'
    | 'top-start'
  >

Description

Whether to flip the placement when the floating element overflows the boundary.

getAnchorRect

Type

(
  element:
    | HTMLElement
    | VirtualElement,
) => {
  height?: number
  width?: number
  x?: number
  y?: number
}

Description

Function that returns the anchor rect

gutter

Type

number

Description

The main axis offset or gap between the reference and floating element

hideWhenDetached

Type

boolean

Description

Whether the popover should be hidden when the reference element is detached

listeners

Type

| boolean
| {
    ancestorResize?: boolean
    ancestorScroll?: boolean
    animationFrame?: boolean
    elementResize?: boolean
    layoutShift?: boolean
  }

Description

Options to activate auto-update listeners

offset

Type

{
  crossAxis?: number
  mainAxis?: number
}

Description

The offset of the floating element

onComplete

Type

(
  data: ComputePositionReturn,
) => void

Description

Function called when the placement is computed

onPositioned

Type

(data: {
  placed: boolean
}) => void

Description

Function called when the floating element is positioned or not

overflowPadding

Type

number

Description

The virtual padding around the viewport edges to check for overflow

overlap

Type

boolean

Description

Whether the floating element can overlap the reference element

placement

Type

| 'bottom'
| 'bottom-end'
| 'bottom-start'
| 'left'
| 'left-end'
| 'left-start'
| 'right'
| 'right-end'
| 'right-start'
| 'top'
| 'top-end'
| 'top-start'

Description

The initial placement of the floating element

sameWidth

Type

boolean

Description

Whether to make the floating element same width as the reference element

shift

Type

number

Description

The secondary axis offset or gap between the reference and floating elements

slide

Type

boolean

Description

Whether the popover should slide when it overflows.

strategy

Type

| 'absolute'
| 'fixed'

Description

The strategy to use for positioning

updatePosition

Type

(data: {
  updatePosition: () => Promise<void>
}) => void | Promise<void>

Description

A callback that will be called when the popover needs to calculate its position.

Last updated on Apr 24, 2026 by Ryan Bower

Toast Notification

Tree