useTooltipTrigger

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

API#

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
• Warmup/Cooldown global times

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:

useTooltip returns props to be spread onto the tooltip:

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

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.

import {useTooltipTriggerState} from '@react-stately/tooltip';
import {mergeProps} from '@react-aria/utils';

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

  return (
    <span
      style={{
        position: 'absolute',
        right: '-10px',
        top: '0',
        transform: 'translateX(100%)',
        backgroundColor: 'white',
        color: 'black',
        padding: '5px'
      }}
      {...mergeProps(props, tooltipProps)}>
      {props.children}
    </span>
  );
}

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

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

  return (
    <span style={{position: 'relative'}}>
      <button ref={ref} {...triggerProps}>
        I have a tooltip
      </button>
      {state.isOpen && (
        <Tooltip {...tooltipProps}>
          And the tooltip tells you more information.
        </Tooltip>
      )}
    </span>
  );
}

<Example />

import {useTooltipTriggerState} from '@react-stately/tooltip';
import {mergeProps} from '@react-aria/utils';

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

  return (
    <span
      style={{
        position: 'absolute',
        right: '-10px',
        top: '0',
        transform: 'translateX(100%)',
        backgroundColor: 'white',
        color: 'black',
        padding: '5px'
      }}
      {...mergeProps(props, tooltipProps)}>
      {props.children}
    </span>
  );
}

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

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

  return (
    <span style={{position: 'relative'}}>
      <button ref={ref} {...triggerProps}>
        I have a tooltip
      </button>
      {state.isOpen && (
        <Tooltip {...tooltipProps}>
          And the tooltip tells you more information.
        </Tooltip>
      )}
    </span>
  );
}

<Example />

import {useTooltipTriggerState} from '@react-stately/tooltip';
import {mergeProps} from '@react-aria/utils';

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

  return (
    <span
      style={{
        position:
          'absolute',
        right: '-10px',
        top: '0',
        transform:
          'translateX(100%)',
        backgroundColor:
          'white',
        color: 'black',
        padding: '5px'
      }}
      {...mergeProps(
        props,
        tooltipProps
      )}>
      {props.children}
    </span>
  );
}

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

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

  return (
    <span
      style={{
        position:
          'relative'
      }}>
      <button
        ref={ref}
        {...triggerProps}>
        I have a tooltip
      </button>
      {state.isOpen && (
        <Tooltip
          {...tooltipProps}>
          And the tooltip
          tells you more
          information.
        </Tooltip>
      )}
    </span>
  );
}

<Example />

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.