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 {Tooltip} from "@qualcomm-ui/react/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 prop, and the content of the tooltip is the children.

<Tooltip trigger={<Button emphasis="primary">Hover me</Button>}>
  Hello world!
</Tooltip>

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.

<Tooltip.Root>
  <Tooltip.Trigger>
    <Button emphasis="primary">Hover me</Button>
  </Tooltip.Trigger>
  <Portal>
    <Tooltip.Positioner>
      <Tooltip.Content>
        <Tooltip.Arrow>
          <Tooltip.ArrowTip />
        </Tooltip.Arrow>
        Hello world!
      </Tooltip.Content>
    </Tooltip.Positioner>
  </Portal>
</Tooltip.Root>

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 {type ReactElement, useState} from "react"

import {selectCollection} from "@qualcomm-ui/core/select"
import type {Placement} from "@qualcomm-ui/dom/floating-ui"
import {Select} from "@qualcomm-ui/react/select"
import {Tooltip} from "@qualcomm-ui/react/tooltip"

const positions = selectCollection({
  items: [
    "top-start",
    "top",
    "top-end",
    "right-start",
    "right",
    "right-end",
    "bottom-start",
    "bottom",
    "bottom-end",
    "left-start",
    "left",
    "left-end",
  ],
})

export function TooltipPlacementDemo(): ReactElement {
  const [placement, setPlacement] = useState<Placement>("top")

  return (
    <div className="w-48">
      <Tooltip
        positioning={{placement}}
        trigger={
          <Select
            aria-label="Select a position"
            collection={positions}
            onValueChange={(value) => setPlacement(value[0] as Placement)}
            positioning={{sameWidth: true}}
            value={[placement]}
          />
        }
      >
        {placement}
      </Tooltip>
    </div>
  )
}

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 by using the closeOnClick and closeOnEscape props.

<Tooltip
  closeOnClick={false}
  closeOnEscape={false}
  trigger={<Button emphasis="primary">Hover me</Button>}
>
  Hello world!
</Tooltip>

Controlled Visibility

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

The tooltip is hidden

import {type ReactElement, useState} from "react"

import {Button} from "@qualcomm-ui/react/button"
import {Tooltip} from "@qualcomm-ui/react/tooltip"

export function TooltipControlledStateDemo(): ReactElement {
  const [open, setOpen] = useState(false)

  return (
    <div className="flex w-40 flex-col items-center gap-4">
      <Tooltip
        onOpenChange={setOpen}
        open={open}
        trigger={<Button emphasis="primary">Hover me</Button>}
      >
        Hello world!
      </Tooltip>

      <output className="font-body-sm text-neutral-primary flex">
        The tooltip is {open ? "visible" : "hidden"}
      </output>
    </div>
  )
}

Disabled

You can disable the tooltip by using the disabled prop.

import {type ReactElement, useState} from "react"

import {Button} from "@qualcomm-ui/react/button"
import {Tooltip} from "@qualcomm-ui/react/tooltip"

export function TooltipDisabledDemo(): ReactElement {
  const [disabled, setDisabled] = useState(true)
  return (
    <div className="flex flex-col items-center gap-4">
      <Tooltip
        disabled={disabled}
        trigger={<Button emphasis="primary">Hover me</Button>}
      >
        Hello world!
      </Tooltip>

      <Button onClick={() => setDisabled(!disabled)} variant="outline">
        {disabled ? "Enable" : "Disable"} tooltip
      </Button>
    </div>
  )
}

Shortcuts

Shortcuts are enabled for common use cases.

Arrow

If you don't wish to customize the arrow tip, you can omit it and Tooltip.Arrow will render the default one. At that, <Tooltip.Arrow /> is equivalent to:

<Tooltip.Arrow>
  <Tooltip.ArrowTip />
</Tooltip.Arrow>

API

The simple tooltip extends the Tooltip.Root component with the following props:

Prop	Type	Default
trigger ^* React children render prop. The tooltip trigger event handlers and attributes are applied to this element. It must forward its ref	BindingRenderProp<TooltipTriggerBindings>
arrowProps Props applied to the arrow element.	TooltipArrowProps
arrowTipProps Props applied to the arrow tip element.	TooltipArrowTipProps
contentProps Props applied to the content element.	TooltipContentProps
hideArrow Whether to hide the arrow.	boolean	false
portalProps Props applied to the portal element.	PortalProps
positionerProps Props applied to the positioner element.	TooltipPositionerProps

trigger

Type

BindingRenderProp<TooltipTriggerBindings>

Description

React children render prop. The tooltip trigger event handlers and attributes are applied to this element. It must forward its ref

arrowProps

Type

TooltipArrowProps

Description

Props applied to the arrow element.

arrowTipProps

Type

TooltipArrowTipProps

Description

Props applied to the arrow tip element.

contentProps

Type

TooltipContentProps

Description

Props applied to the content element.

hideArrow

Type

boolean

Description

Whether to hide the arrow.

portalProps

Type

PortalProps

Description

Props applied to the portal element.

positionerProps

Type

TooltipPositionerProps

Description

Props applied to the positioner element.

Composite API

The main component that wraps the trigger and the content elements. Doesn't render anything by itself.

Prop	Type	Default
children React children prop.	ReactNode
closeOnClick Whether the tooltip should close when the trigger is clicked.	boolean
closeOnEscape Whether the tooltip should close when the escape key is pressed.	boolean
dir The document's text/writing direction.	'ltr' \| 'rtl'	'ltr'
disabled Controls the component's interactivity. If `true`, the component's trigger element will not activate the tooltip.	boolean
onOpenChange Function called when the tooltip is opened/closed.	( open: boolean, ) => void
open The open state of the tooltip.	boolean
positioning The user provided options used to position the popover content	TooltipPositioningOptions

children

Type

ReactNode

Description

React children prop.

closeOnClick

Type

boolean

Description

Whether the tooltip should close when the trigger is clicked.

closeOnEscape

Type

boolean

Description

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

dir

Type

'ltr' | 'rtl'

Description

The document's text/writing direction.

disabled

Type

boolean

Description

Controls the component's interactivity. If true, the component's trigger element will not activate the tooltip.

onOpenChange

Type

(
  open: boolean,
) => void

Description

Function called when the tooltip is opened/closed.

open

Type

boolean

Description

The open state of the tooltip.

positioning

Type

TooltipPositioningOptions

Description

The user provided options used to position the popover content

<Tooltip.Trigger>

A trigger that opens the tooltip. Doesn't render anything by itself. Applies event handlers and attributes to the child element.

Prop	Type
children ^* React children Render Prop	BindingRenderProp<TooltipTriggerBindings>
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string

children

Type

BindingRenderProp<TooltipTriggerBindings>

Description

React children Render Prop

Type

string

Description

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

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

The element that positions the tooltip content relative to the trigger. Renders a <div> element by default.

Prop	Type
children React children prop.	ReactNode
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

Type

string

Description

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

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

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

className

Value

'qui-tooltip__positioner'

data-tooltip-part

Value

'positioner'

style

Value

CSSProperties

The content of the tooltip which is displayed relative to the trigger. Renders a <div> element by default.

Prop	Type
children React children prop.	ReactNode
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

Type

string

Description

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

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'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

className

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

The container that positions the arrow. This element renders the <Tooltip.ArrowTip/> by default if no children are provided.

Prop	Type
children React children prop.	ReactNode
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

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

The arrow tip element. Renders a <div> element by default.

Prop	Type
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Attribute / Property	Value
`className`	'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 May 23, 2026 by Ryan Bower

Toast Notification

Tree

Tooltip

Overview

Examples

Simple

Composite

Placement

Close On Click / Escape

Controlled Visibility

Disabled

Shortcuts

Arrow

API

<Tooltip>

Composite API

<Tooltip.Root>

<Tooltip.Trigger>

<Tooltip.Positioner>

<Tooltip.Content>

<Tooltip.Arrow>

<Tooltip.ArrowTip>

TooltipPositioningOptions