useTooltipTrigger

Provides the behavior and accessibility implementation for a tooltip trigger, e.g. a button that shows a description when focused or hovered.

install	`yarn add react-aria`
version	3.29.1
usage	`import {useTooltipTrigger, useTooltip} from 'react-aria'`

View ARIA pattern

W3C

API#

useTooltipTrigger(
  props: TooltipTriggerProps,
  state: TooltipTriggerState,
  ref: RefObject<FocusableElement>
): TooltipTriggerAria

useTooltip(
  (props: AriaTooltipProps,
  , state?: TooltipTriggerState
)): TooltipAria

Features#

The HTML title attribute can be used to create a tooltip, but it cannot be styled. Custom styled tooltips can be hard to build in an accessible way. useTooltipTrigger and useTooltip help build fully accessible tooltips that can be styled as needed.

Keyboard focus management and cross browser normalization
Hover management and cross browser normalization
Labeling support for screen readers (aria-describedby)
Exposed as a tooltip to assistive technology via ARIA
Matches native tooltip behavior with delay on hover of first tooltip and no delay on subsequent tooltips.

Anatomy#

A tooltip consists of two parts: the trigger element and the tooltip itself. Users may reveal the tooltip by hovering or focusing the trigger.

useTooltipTrigger returns props to be spread onto its target trigger and the tooltip:

Name	Type	Description
`triggerProps`	`DOMAttributes & PressProps & HoverProps & FocusEvents`	Props for the trigger element.
`tooltipProps`	`DOMAttributes`	Props for the overlay container element.

useTooltip returns props to be spread onto the tooltip:

Name	Type	Description
`tooltipProps`	`DOMAttributes`	Props for the tooltip element.

Tooltip state is managed by the useTooltipTriggerState hook in @react-stately/tooltip. The state object should be passed as an option to useTooltipTrigger and useTooltip.

Example#

This example implements a Tooltip that renders in an absolute position next to its target. The useTooltip hook applies the correct ARIA attributes to the tooltip, and useTooltipTrigger associates it to the trigger element.

Two instances of the example are rendered to demonstrate the behavior of the delay on hover. If you hover over the first button, the tooltip will be shown after a delay. Hovering over the second button shows the tooltip immediately. If you wait for a delay before hovering another element, the delay restarts.

import {useTooltipTriggerState} from 'react-stately';
import {mergeProps, useTooltip, useTooltipTrigger} from 'react-aria';

function Tooltip({ state, ...props }) {
  let { tooltipProps } = useTooltip(props, state);

  return (
    <span
      style={{
        position: 'absolute',
        left: '5px',
        top: '100%',
        maxWidth: 150,
        marginTop: '10px',
        backgroundColor: 'white',
        color: 'black',
        padding: '5px',
        border: '1px solid gray'
      }}
      {...mergeProps(props, tooltipProps)}
    >
      {props.children}
    </span>
  );
}

function TooltipButton(props) {
  let state = useTooltipTriggerState(props);
  let ref = React.useRef(null);

  // Get props for the trigger and its tooltip
  let { triggerProps, tooltipProps } = useTooltipTrigger(props, state, ref);

  return (
    <span style={{ position: 'relative' }}>
      <button
        ref={ref}
        {...triggerProps}
        style={{ fontSize: 18 }}
        onClick={() => alert('Pressed button')}
      >
        {props.children}
      </button>
      {state.isOpen && (
        <Tooltip state={state} {...tooltipProps}>{props.tooltip}</Tooltip>
      )}
    </span>
  );
}

<TooltipButton tooltip="Edit">✏️</TooltipButton>
<TooltipButton tooltip="Delete">🚮</TooltipButton>

import {useTooltipTriggerState} from 'react-stately';
import {
  mergeProps,
  useTooltip,
  useTooltipTrigger
} from 'react-aria';

function Tooltip({ state, ...props }) {
  let { tooltipProps } = useTooltip(props, state);

  return (
    <span
      style={{
        position: 'absolute',
        left: '5px',
        top: '100%',
        maxWidth: 150,
        marginTop: '10px',
        backgroundColor: 'white',
        color: 'black',
        padding: '5px',
        border: '1px solid gray'
      }}
      {...mergeProps(props, tooltipProps)}
    >
      {props.children}
    </span>
  );
}

function TooltipButton(props) {
  let state = useTooltipTriggerState(props);
  let ref = React.useRef(null);

  // Get props for the trigger and its tooltip
  let { triggerProps, tooltipProps } = useTooltipTrigger(
    props,
    state,
    ref
  );

  return (
    <span style={{ position: 'relative' }}>
      <button
        ref={ref}
        {...triggerProps}
        style={{ fontSize: 18 }}
        onClick={() => alert('Pressed button')}
      >
        {props.children}
      </button>
      {state.isOpen && (
        <Tooltip state={state} {...tooltipProps}>
          {props.tooltip}
        </Tooltip>
      )}
    </span>
  );
}

<TooltipButton tooltip="Edit">✏️</TooltipButton>
<TooltipButton tooltip="Delete">🚮</TooltipButton>

import {useTooltipTriggerState} from 'react-stately';
import {
  mergeProps,
  useTooltip,
  useTooltipTrigger
} from 'react-aria';

function Tooltip(
  { state, ...props }
) {
  let { tooltipProps } =
    useTooltip(
      props,
      state
    );

  return (
    <span
      style={{
        position:
          'absolute',
        left: '5px',
        top: '100%',
        maxWidth: 150,
        marginTop:
          '10px',
        backgroundColor:
          'white',
        color: 'black',
        padding: '5px',
        border:
          '1px solid gray'
      }}
      {...mergeProps(
        props,
        tooltipProps
      )}
    >
      {props.children}
    </span>
  );
}

function TooltipButton(
  props
) {
  let state =
    useTooltipTriggerState(
      props
    );
  let ref = React.useRef(
    null
  );

  // Get props for the trigger and its tooltip
  let {
    triggerProps,
    tooltipProps
  } = useTooltipTrigger(
    props,
    state,
    ref
  );

  return (
    <span
      style={{
        position:
          'relative'
      }}
    >
      <button
        ref={ref}
        {...triggerProps}
        style={{
          fontSize: 18
        }}
        onClick={() =>
          alert(
            'Pressed button'
          )}
      >
        {props.children}
      </button>
      {state.isOpen && (
        <Tooltip
          state={state}
          {...tooltipProps}
        >
          {props.tooltip}
        </Tooltip>
      )}
    </span>
  );
}

<TooltipButton tooltip="Edit">
  ✏️
</TooltipButton>
<TooltipButton tooltip="Delete">
  🚮
</TooltipButton>

Usage#

The following examples show how to use the TooltipButton component created in the above example.

Delay#

Tooltips appear after a short delay when hovering the trigger, or instantly when using keyboard focus. This delay can be adjusted for hover using the delay prop.

<TooltipButton tooltip="Save" delay={0}>💾</TooltipButton>

<TooltipButton tooltip="Save" delay={0}>💾</TooltipButton>

<TooltipButton
  tooltip="Save"
  delay={0}
>
  💾
</TooltipButton>

Close Delay#

Tooltips disappear after a short delay when no longer hovering the trigger, or instantly when using keyboard focus. This delay can be adjusted for hover using the closeDelay prop.

<TooltipButton tooltip="Refresh" closeDelay={0}>🔄</TooltipButton>

<TooltipButton tooltip="Refresh" closeDelay={0}>
  🔄
</TooltipButton>

<TooltipButton
  tooltip="Refresh"
  closeDelay={0}
>
  🔄
</TooltipButton>

Trigger#

By default, tooltips appear both on hover and on focus. The trigger prop can be set to "focus" to display the tooltip only on focus, and not on hover.

<TooltipButton tooltip="Burn CD" trigger="focus">💿</TooltipButton>

<TooltipButton tooltip="Burn CD" trigger="focus">
  💿
</TooltipButton>

<TooltipButton
  tooltip="Burn CD"
  trigger="focus"
>
  💿
</TooltipButton>

Controlled open state#

The open state of the tooltip can be controlled via the defaultOpen and isOpen props.

function Example() {
  let [isOpen, setOpen] = React.useState(false);

  return (
    <>
      <p>Tooltip is {isOpen ? 'showing' : 'not showing'}</p>
      <TooltipButton
        tooltip="Notifications"
        isOpen={isOpen}
        onOpenChange={setOpen}
      >
        📣
      </TooltipButton>
    </>
  );
}

function Example() {
  let [isOpen, setOpen] = React.useState(false);

  return (
    <>
      <p>Tooltip is {isOpen ? 'showing' : 'not showing'}</p>
      <TooltipButton
        tooltip="Notifications"
        isOpen={isOpen}
        onOpenChange={setOpen}
      >
        📣
      </TooltipButton>
    </>
  );
}

function Example() {
  let [isOpen, setOpen] =
    React.useState(
      false
    );

  return (
    <>
      <p>
        Tooltip is{' '}
        {isOpen
          ? 'showing'
          : 'not showing'}
      </p>
      <TooltipButton
        tooltip="Notifications"
        isOpen={isOpen}
        onOpenChange={setOpen}
      >
        📣
      </TooltipButton>
    </>
  );
}

Disabled#

The isDisabled prop can be provided to a TooltipTrigger to disable the tooltip, without disabling the trigger it displays on.

<TooltipButton tooltip="Print" isDisabled>🖨</TooltipButton>

<TooltipButton tooltip="Print" isDisabled>🖨</TooltipButton>

<TooltipButton
  tooltip="Print"
  isDisabled
>
  🖨
</TooltipButton>

Internationalization#

RTL#

In right-to-left languages, tooltips should be mirrored across trigger. Ensure that your CSS and overlay positioning (if any) accounts for this.

Name	Type	Default	Description
`isDisabled`	`boolean`	—	Whether the tooltip should be disabled, independent from the trigger.
`delay`	`number`	`1500`	The delay time for the tooltip to show up. See guidelines.
`closeDelay`	`number`	`500`	The delay time for the tooltip to close. See guidelines.
`trigger`	`'focus'`	—	By default, opens for both focus and hover. Can be made to open only for focus.
`isOpen`	`boolean`	—	Whether the overlay is open by default (controlled).
`defaultOpen`	`boolean`	—	Whether the overlay is open by default (uncontrolled).
`onOpenChange`	`( (isOpen: boolean )) => void`	—	Handler that is called when the overlay's open state changes.

Properties

Name	Type	Description
`isOpen`	`boolean`	Whether the tooltip is currently showing.

Methods

Method	Description
`open( (immediate?: boolean )): void`	Shows the tooltip. By default, the tooltip becomes visible after a delay depending on a global warmup timer. The `immediate` option shows the tooltip immediately instead.
`close( (immediate?: boolean )): void`	Hides the tooltip.

Name	Type	Description
`triggerProps`	`DOMAttributes & PressProps & HoverProps & FocusEvents`	Props for the trigger element.
`tooltipProps`	`DOMAttributes`	Props for the overlay container element.

All DOM attributes supported across both HTML and SVG elements.

Extends: AriaAttributes, ReactDOMAttributes

Name	Type	Description
`id`	`string \| undefined`
`role`	`AriaRole \| undefined`
`tabIndex`	`number \| undefined`
`style`	`CSSProperties \| undefined`
`className`	`string \| undefined`

Name	Type	Description
`isPressed`	`boolean`	Whether the target is in a controlled press state (e.g. an overlay it triggers is open).
`isDisabled`	`boolean`	Whether the press events should be disabled.
`preventFocusOnPress`	`boolean`	Whether the target should not receive focus on press.
`shouldCancelOnPointerExit`	`boolean`	Whether press events should be canceled when the pointer leaves the target while pressed. By default, this is `false`, which means if the pointer returns back over the target while still pressed, onPressStart will be fired again. If set to `true`, the press is canceled when the pointer leaves the target and onPressStart will not be fired if the pointer returns.
`allowTextSelectionOnPress`	`boolean`	Whether text selection should be enabled on the pressable element.
`onPress`	`( (e: PressEvent )) => void`	Handler that is called when the press is released over the target.
`onPressStart`	`( (e: PressEvent )) => void`	Handler that is called when a press interaction starts.
`onPressEnd`	`( (e: PressEvent )) => void`	Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
`onPressChange`	`( (isPressed: boolean )) => void`	Handler that is called when the press state changes.
`onPressUp`	`( (e: PressEvent )) => void`	Handler that is called when a press is released over the target, regardless of whether it started on the target or not.

Properties

Name	Type	Description
`type`	`'pressstart' \| 'pressend' \| 'pressup' \| 'press'`	The type of press event being fired.
`pointerType`	`PointerType`	The pointer type that triggered the press event.
`target`	`Element`	The target element of the press event.
`shiftKey`	`boolean`	Whether the shift keyboard modifier was held during the press event.
`ctrlKey`	`boolean`	Whether the ctrl keyboard modifier was held during the press event.
`metaKey`	`boolean`	Whether the meta keyboard modifier was held during the press event.
`altKey`	`boolean`	Whether the alt keyboard modifier was held during the press event.

Methods

Method	Description
`continuePropagation(): void`	By default, press events stop propagation to parent elements. In cases where a handler decides not to handle a specific event, it can call `continuePropagation()` to allow a parent to handle it.

'mouse'
  | 'pen'
  | 'touch'
  | 'keyboard'
  | 'virtual'

Name	Type	Description
`isDisabled`	`boolean`	Whether the hover events should be disabled.
`onHoverStart`	`( (e: HoverEvent )) => void`	Handler that is called when a hover interaction starts.
`onHoverEnd`	`( (e: HoverEvent )) => void`	Handler that is called when a hover interaction ends.
`onHoverChange`	`( (isHovering: boolean )) => void`	Handler that is called when the hover state changes.

Name	Type	Description
`type`	`'hoverstart' \| 'hoverend'`	The type of hover event being fired.
`pointerType`	`'mouse' \| 'pen'`	The pointer type that triggered the hover event.
`target`	`HTMLElement`	The target element of the hover event.

Name	Type	Description
`onFocus`	`( (e: FocusEvent<Target> )) => void`	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent<Target> )) => void`	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	Handler that is called when the element's focus status changes.

Name	Type	Description
`isOpen`	`boolean`
`id`	`string`	The element's unique identifier. See MDN.
`aria-label`	`string`	Defines a string value that labels the current element.
`aria-labelledby`	`string`	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	Identifies the element (or elements) that provide a detailed, extended description for the object.

Name	Type	Description
`tooltipProps`	`DOMAttributes`	Props for the tooltip element.

Manages state for a tooltip trigger. Tracks whether the tooltip is open, and provides methods to toggle this state. Ensures only one tooltip is open at a time and controls the delay for showing a tooltip.

useTooltipTriggerState(
  (props: TooltipTriggerProps
)): TooltipTriggerState

Provides the accessibility implementation for a Tooltip component.

useTooltip(
  (props: AriaTooltipProps,
  , state?: TooltipTriggerState
)): TooltipAria