NUI-Widgets documentation has moved to Storybook hosted on Github Pages.

Tooltip

import Tooltip from '@concur/nui-widgets/lib/Tooltip/Tooltip';

A tooltip is a lightweight overlay that contains a short message which provides the user context about an unknown or unfamiliar element in an interface.

Using Tooltips

Tooltips are displayed automatically when users hover over (on mouseover) or place focus on a graphical element, such as an icon, image, hyperlink, or form input. They automatically hide when the user moves the mouse (on mouseout) or when focus (blur event) is moved to another element on the page.

Best Practices

Use tooltips:

  • Sparingly. Tooltips can be as distracting as a modal, so don’t use them unless they add significant value.
  • To clarify a control before asking a user to perform an action.
  • When a control doesn’t have a label, or needs a short explanation.
  • Only when relevant. They should be as contextual as possible.
  • To supplement a focusable element. A tooltip will never receive focus.

Avoid using tooltips:

  • When the text inside it is essential to a primary task.
  • To contain elements a user must interact with.
  • To repeat content that is already on the page.
  • On more than 3-4 elements in a row to avoid fatigue.
  • For large blocks of text. Consider using a Popover instead.
  • When preventing a user’s interaction with the application. Consider using a Modal or MessageBox instead.

Examples

Default Tooltip

Tooltips can be used with different components, as shown below. Hover over each element to reveal the tooltip.

<Tooltip
    message='This is a tooltip'
    placement='bottom'>
    <Icon ariaLabel='Icon for hotel' iconName='icon-hotel'
        size='lg'
        tabIndex='0' />
</Tooltip>

<Tooltip
    message='This is a tooltip'
    placement='right'>
    <Button>Open Tooltip</Button>
</Tooltip>

<Tooltip
    message='This is a tooltip'
    placement='left'>
    <Button type='link'>Open Tooltip</Button>
</Tooltip>

<Tooltip
    message='This is a tooltip'
    placement='top'>
    <FormControl />
</Tooltip>

Validation State Tooltip

  • Applies only to Form Group components and is usually initiated by hovering over or focusing on an alert icon.
  • See Form Validation States for more usage and examples.

Usage

Properties

Property Type Default Description
children Node Required React component to which the tooltip will be attached.
message String Required Text to display in the tooltip.
flipContainer Element or Element[]   Used to create a boundary for the underlying Popper to stay within.
placement String or String[] ['right', 'top', 'left', 'bottom'] Placement of the popover relative to the children element. Options are 'auto', 'auto-start', 'auto-end', 'top', 'top-start', 'top-end', 'bottom', 'bottom-start', 'bottom-end', 'left', 'left-start', 'left-end', 'right', 'right-start', 'right-end'. If you use an array of strings, the first item in the array is the default placement and the following ones are chosen in order as fallback placements if the preceding ones don’t work.

Accessibility

Showing a tooltip on hover or when keyboard focus is placed on a focusable element ensures that all users can access it, even if they aren’t using a mouse.

By default, CoreUI components help assistive technology read the tooltip content by building the following into the default component:

  • ARIA role=”tooltip” is built in to the component.
  • Tooltip is given an ID which is used as the value of the aria-describedby attribute of the DOM element it describes.

Resources