## Usage

This `<Tooltip />` component is primarily used to provide a hint or tip on what a tool or other interaction does. They are meant to clarify or help you use the element they are displayed over.

If you need to display interactive content inside the tooltip, use the [Popover](/packages/popover/) component instead.

<Notice>
  <Text>
    Tooltips are not supported on touch devices. If you're designing a touch-based user experience, consider other ways
    to display your content.
  </Text>
</Notice>

```tsx live
<Tooltip label="I am a tooltip label that aims to help you use the trigger I'm displayed over.">
  <Button label="Trigger" />
</Tooltip>
```

- The tooltip shows after 300 ms after hovering over the trigger.
- It displays instantly on keyboard focus of the trigger.
- It remains visible when hovering over the tooltip itself.
- It closes on `ESC` keypress, tabbing away or hovering outside.
- It has a max width of `16rem` which will make the label text wrap to multiple lines if overflowing.

## Label

Keep the tooltip's `label` short, informative and clear. **As a rule of thumb**, it should never contain any crucial information the user needs to complete their task, but merely act as an aid to help the user gain confidence when they seek it out.

## On buttons and links

Tooltips are most commonly used around interactive elements. EDS supports tooltips around the `<Button />`, `<ButtonLink />` and `<Link />` components in particular. Simply wrap your interactive trigger with a `<Tooltip />` and you're good to go.

If your tooltip label contains _additional_ information that is not conveyed in the interactive trigger's label or placeholder, remember to set `ariaHidden={false}` to make sure screen readers announce the tooltip label.

```tsx live
const tooltipLabel = 'I am a tooltip label.';

return (
  <Flex flexWrap="wrap" gap="medium" alignItems="center">
    <Tooltip label={tooltipLabel} ariaHidden={false}>
      <Button tone="neutral" label="Button" />
    </Tooltip>

    <Tooltip label={tooltipLabel} ariaHidden={false}>
      <ButtonLink label="ButtonLink" href="#" />
    </Tooltip>

    <Tooltip label={tooltipLabel} ariaHidden={false}>
      <Link label="Link" href="#" />
    </Tooltip>
  </Flex>
);
```

### Icon-only buttons

EDS recommends to not use tooltips to explain what an icon-only button means or does. If the icon is not considered intuitive enough for sighted users, then always consider having a visual label on the button.

However – sometimes it's unavoidable due to limited screen real estate and when the icons used are considered intuitive enough for experienced users – in which case a tooltip makes it more inclusive. In this situation it's important that the icon-only button label conveys the same thing as the tooltip label – they both should describe what the button does – because they will be presented in separate ways depending on the type of user.

- Sighted users are able to read the **tooltip label** on button hover or focus.
- Non-sighted users are able to read the **button label** on button focus. The tooltip has a default `ariaHidden = true` for this reason, to avoid announcing what the button does twice by screen readers.

```tsx live
<Tooltip label="Add an employee">
  <Button icon={AddIcon} iconOnly tone="neutral" label="Add an employee" />
</Tooltip>
```

## On non-interactive elements

Tooltips can in rare cases be used on non-interactive elements, for example a piece of text. Since they natively can't receive focus you need to set the `nonInteractiveChild` prop to `true`, which renders a `<div tabindex="0" />` around the children to enable keyboard accessibility and ensure that `data-state` and `aria-describedby` props can be spread onto the focusable element.

NOTE: Doing this might annoy keyboard-only users as it adds an unexpected focus stop when tabbing through interactive elements (buttons, inputs, links etc). Also make sure to adjust the `ariaHidden` prop to `false` so that assistive tech can read out the tooltip label if it contains additional content.

```tsx live
<Tooltip label="Friday, 16 August 2024, 1:25 pm" nonInteractiveChild ariaHidden={false}>
  <Text color="neutralSubtle" fontWeight="medium" fontSize="small">
    Updated yesterday
  </Text>
</Tooltip>
```

**Although EDS recommends against** "hiding" information in a tooltip over just an icon, sometimes it's unavoidable. Always consider other ways to present this information before reaching for an icon + tooltip.

In the example below, we show how to use a tooltip around an `<InformativeIcon />` whilst remaining an accessible experience for mouse pointer, keyboard-only and screen reader users (with caveats).

- Pointer users are able to hover over the icon to read the tooltip label.
- Keyboard-only users are able to tab to the icon to read the tooltip label.
- Screen reader users are able to navigate via keyboard arrows to the `<VisuallyHidden />` element to read the tooltip label. NOTE: If they tab to the icon (which is an unexpected focus stop) they will also hear the tooltip label but won't be able to follow any screen readers instructions that might be announced.

```tsx live
const message = 'I am a tooltip label.';

return (
  <>
    <Tooltip label={message} nonInteractiveChild ariaHidden={false}>
      <InformativeIcon color="neutralSubtle" size="small" />
    </Tooltip>

    <VisuallyHidden>{message}</VisuallyHidden>
  </>
);
```

### On disabled buttons

EDS generally recommends against disabling buttons or other interactive elements, because it forces the user to find the reason why they're disabled. In most cases, it's better to let the interactive element always be enabled, and if the interaction it triggers fails or is not available, then let the user know why with a [Notice](/packages/notice/) or a [Toast](/packages/toast/) instead.

However – in some cases this might not be a good viable option. Then we recommend to provide a tooltip around the disabled element to let the user know instantly why it's not available.

Since `disabled` elements **natively can't receive focus**, you need to add the `nonInteractiveChild` prop and `ariaHidden={false}` to the `<Tooltip />` that wraps your disabled button.

```tsx live
<Flex>
  <Tooltip label="Description of why this button is disabled right now." nonInteractiveChild ariaHidden={false}>
    <Button label="Disabled button" disabled />
  </Tooltip>
</Flex>
```

## Positioning

Use the `side` and `align` props to set the position of the tooltip in relation to the trigger. Its default position in relation to the trigger is "bottom center".

NOTE: The positioning will automatically be overridden if the tooltip can't fit within the viewport. If you need to prevent this, you can set the `forcePosition` prop to `true`, although it's recommended to leave it as is.

### Side

```tsx live
<Flex flexWrap="wrap" gap="medium">
  <Tooltip label="I am a tooltip label that aims to explain the related trigger element." side="bottom">
    <Button tone="neutral" label="Bottom (default)" />
  </Tooltip>

  <Tooltip label="I am a tooltip label that aims to explain the related trigger element." side="left">
    <Button tone="neutral" label="Left" />
  </Tooltip>

  <Tooltip label="I am a tooltip label that aims to explain the related trigger element." side="top">
    <Button tone="neutral" label="Top" />
  </Tooltip>

  <Tooltip label="I am a tooltip label that aims to explain the related trigger element." side="right">
    <Button tone="neutral" label="Right" />
  </Tooltip>
</Flex>
```

### Align

```tsx live
<Flex flexWrap="wrap" gap="medium">
  <Tooltip label="I am a tooltip label that aims to explain the related trigger element.">
    <Button tone="neutral" label="Center (default)" />
  </Tooltip>

  <Tooltip label="I am a tooltip label that aims to explain the related trigger element." align="start">
    <Button tone="neutral" label="Start" />
  </Tooltip>

  <Tooltip label="I am a tooltip label that aims to explain the related trigger element." align="end">
    <Button tone="neutral" label="End" />
  </Tooltip>
</Flex>
```

## Positioning issues

If you're getting positioning issues when wrapping an element with the tooltip it's most likely because the tooltip is placed in a container element with a display mode that controls the layout of its children, such as Flexbox or CSS Grid.

### Grid container example

The parent container (`<Grid />`) does not define any align/justify properties and will by default stretch any children on the x- and/or y-axis, in this case the `<div>` that wraps the Tooltip's children to make them interactive.

Try hovering over or tabbing to the badge in the example below to see the issue.

```tsx live
<Grid gridTemplateColumns="1fr 1fr" gap="xlarge">
  <Box width={100} height={60} backgroundColor="neutralSubtle" />

  <Tooltip label="I am a tooltip." nonInteractiveChild>
    <Badge tone="neutral" label="A badge example" />
  </Tooltip>
</Grid>
```

The simplest solution is to wrap the `<Tooltip />` in a `<Box />` which will cause the parent Grid to stretch the Box instead.

```tsx live
<Grid gridTemplateColumns="1fr 1fr" gap="xlarge">
  <Box width={100} height={60} backgroundColor="neutralSubtle" />

  <Box>
    <Tooltip label="I am a tooltip." nonInteractiveChild>
      <Badge tone="neutral" label="A badge example" />
    </Tooltip>
  </Box>
</Grid>
```

### Block container example

A similar but different issue can occur when the parent container is a `block` element, but you're trigger (children of the Tooltip) is an `inline-flex` element.

Try hovering over or tabbing to the badge in the example below to see the issue.

```tsx live
<Box>
  <Tooltip label="I am a tooltip label." nonInteractiveChild ariaHidden={false}>
    <Flex inline padding="xlarge" backgroundColor="informativeSubtle">
      I am an inline-flex div.
    </Flex>
  </Tooltip>
</Box>
```

To fix this, simply make the parent container use Flexbox instead.

```tsx live
<Flex>
  <Tooltip label="I am a tooltip label." nonInteractiveChild ariaHidden={false}>
    <Flex inline padding="xlarge" backgroundColor="informativeSubtle">
      I am an inline-flex div.
    </Flex>
  </Tooltip>
</Flex>
```

## Resources

- [Tooltips in the time of WCAG 2.1](https://sarahmhigley.com/writing/tooltips-in-wcag-21/)
- [The Trials and Tribulations of the Title Attribute](https://www.24a11y.com/2017/the-trials-and-tribulations-of-the-title-attribute/)
- [Nielsen Norman Group - Tooltip Guidelines](https://www.nngroup.com/articles/tooltip-guidelines/)

Floating labels that briefly explain the function of a user interface element.

Tooltip

Accessibility

Responsive layouts

Tokens

Foundations

a11y

Accordion

Actions

AddressInput

AppLayout

Avatar

Badge

Blanket

Breadcrumbs

BulkActionBar

Button

Card

Checkbox

Core

DateDropdown

DateInput

Divider

EmptyState

Field

Fieldset

FileInput

Filtering

Flex

Grid

Heading

Icon

Illustration

Link

List

Loading

MdxContentPages

Modal

Notice

PageHeader

Pagination

PhoneInput

Popover

Radio

RailTrack

RichTextEditor

ScrollWrap

SearchInput

SelectDropdown

SelectInput

ShowMore

Table

Tabs

Text

TextAreaInput

TextInput

Toast

Toggle

Utils

Utils - NextJS

UtilsComponents

Components

Forms

Search

Tables

Patterns

Introduction

Product tone and voice

Capitalisation

Date and time

Inclusive design

Content

Welcome to EDS

Start designing

Start developing

Contributing

Releases

The EDS way

Coding style guide

Guide to Pendo

Setting up the EDS repo

Creating a new package

Automated testing

PR and changeset process

Publishing snapshots

Publishing packages

Monorepo tools

Team resources

The trigger for your tooltip. Hovering or focusing on this element will show the tooltip.

children

label

Use when your tooltip trigger (children) is not a button or link element.

When true, will wrap children of the tooltip in a `<div tabindex="0" />` to enable keyboard accessibility
and ensure that the primitive can inject props like `data-state` (controls the open state) and
`aria-describedby` (screen reader a11y) onto it. Defaults to `false`.

nonInteractiveChild

The preferred side of the trigger to render against when open. Will be reversed when collisions
occur and `forcePosition` is enabled. Defaults to `bottom`.

side

The preferred alignment against the trigger. May change when collisions occur. Defaults to `center`.

align

When true, it will force the tooltip to its `side` and `align` positioning,
and ignore any adjustments when collisions with the viewport boundaries happen. Defaults to `false`.

forcePosition

Hides the tooltip label from assistive technologies. Defaults to `true`.

ariaHidden

Prop	Required	Description	Type
`children`	✅	The trigger for your tooltip. Hovering or focusing on this element will show the tooltip.	string \| number \| false \| true \| ReactElement<any, string \| JSXElementConstructor<any>> \| ReactPortal \| { key?: string \| number; ref?: null; props?: { children?: boolean \| ReactChild \| ReactPortal \| StrictReactFragment; }; } \| (boolean \| ReactChild \| ReactPortal \| StrictReactFragment)[]
`label`	✅	The content inside the tooltip.	string \| number \| false \| true \| ReactElement<any, string \| JSXElementConstructor<any>> \| ReactPortal \| { key?: string \| number; ref?: null; props?: { children?: boolean \| ReactChild \| ReactPortal \| StrictReactFragment; }; } \| (boolean \| ReactChild \| ReactPortal \| StrictReactFragment)[]
`nonInteractiveChild`	—	Use when your tooltip trigger (children) is not a button or link element. When true, will wrap children of the tooltip in a <div tabindex="0" /> to enable keyboard accessibility and ensure that the primitive can inject props like data-state (controls the open state) and aria-describedby (screen reader a11y) onto it. Defaults to false.	boolean
`side`	—	The preferred side of the trigger to render against when open. Will be reversed when collisions occur and forcePosition is enabled. Defaults to bottom.	"top" \| "right" \| "bottom" \| "left"
`align`	—	The preferred alignment against the trigger. May change when collisions occur. Defaults to center.	"start" \| "center" \| "end"
`forcePosition`	—	When true, it will force the tooltip to its side and align positioning, and ignore any adjustments when collisions with the viewport boundaries happen. Defaults to false.	boolean
`ariaHidden`	—	Hides the tooltip label from assistive technologies. Defaults to true.	boolean