---
title: Tooltip
description: Tooltip displays a description of an element on hover or focus.
thumbnail:
  image: /previews/components/core/tooltip.jpeg
  video: /previews/components/core/tooltip.mp4
links:
  - label: Aria docs
    href: https://react-spectrum.adobe.com/react-aria/Tooltip.html
  - label: Aria API Reference
    href: https://react-spectrum.adobe.com/react-aria/Tooltip.html#props
  - label: Report an issue
    href: https://github.com/mehdibha/dotUI/issues/new/choose
  - label: Edit this page
    href: https://github.com/mehdibha/dotUI/tree/main/content/components/overlay/tooltip.mdx?plain=1
---

<ComponentPreview
  name="core/tooltip-default"
  preview={`<Tooltip content="Add to library">
    <Button><PlusIcon /></Button>
  </Tooltip>`}
/>

## Installation

<Tabs items={["CLI", "Manual"]}>
  <Tab value="CLI">
  
  ```package-install
npx dotui-cli@latest add tooltip
```

  </Tab>
  <Tab value="manual">
  
    <Steps>
      <Step>Install the following dependencies:</Step>

    ```package-install
    react-aria-components
    ```

      <Step>Copy and paste the following code into your project.</Step>
      <ComponentSource name="core/tooltip" />
      <Step>Update the import paths to match your project setup.</Step>
    </Steps>

  </Tab>
</Tabs>

## Usage

Use `Tooltip` to display a description of an element on hover or focus.

### Best practices

- Use tooltips to describe icons (e.g., icon buttons).
- Keep the tooltip text minimal.
- Never include tooltips on non-interactive components (div, span, p) because it will not be accessible for keyboard or screen reader users.
- Don't place actions inside a tooltip

## Options

### Arrow

<ComponentPreview
  name="core/tooltip-arrow"
  preview={`<Tooltip content="Add to library" arrow>
    <Button><PlusIcon /></Button>
  </Tooltip>`}
/>

### Placement

The Tooltip's placement with respect to its trigger element can be adjusted using the `placement` prop. See the props table for a full list of available placement combinations.

<ComponentPreview
  name="core/tooltip-placement"
  preview={`<Tooltip placement="top" content="Add to library"><Button /></Tooltip>
<Tooltip placement="bottom" content="Add to library"><Button /></Tooltip>
<Tooltip placement="left" content="Add to library"><Button /></Tooltip>
<Tooltip placement="right" content="Add to library"><Button /></Tooltip>`}
/>

### Should flip

This option determines whether or not a tooltip should be able to switch sides when constrained by space.

<ComponentPreview
  name="core/tooltip-flip"
  preview={`<Tooltip shouldFlip={shouldFlip} content="Add to library">
    <Button><PlusIcon /></Button>
  </Tooltip>`}
/>

### Offset

The offset is the distance between the end of the tip and the target.

<ComponentPreview
  name="core/tooltip-offset"
  preview={`<Tooltip offset={offset} content="Add to library">
    <Button><PlusIcon /></Button>
  </Tooltip>`}
/>

### Container padding

To make sure that the tooltip will stay within certain boundaries (e.g., a browser window) it's possible to define a container and a container padding value to respect. The default value for this is 12 px.

<ComponentPreview
  name="core/tooltip-container-padding"
  preview={`<Tooltip containerPadding={containerPadding} content="Add to library">
    <Button><PlusIcon /></Button>
  </Tooltip>`}
/>

### Delay

The delay duration (the time from when the mouse enters a tooltip trigger until the tooltip opens) and the close delay can be customised.

<ComponentPreview
  name="core/tooltip-delay"
  preview={`<Tooltip delay={delay} closeDelay={closeDelay} content="Add to library">
    <Button><PlusIcon /></Button>
  </Tooltip>`}
/>

## Composition

For more flexibility, you can use the composition pattern to create a custom tooltip.

<ComponentPreview
  name="core/tooltip-composition"
  preview={`<TooltipRoot>
    <Button>Hover</Button>
    <TooltipContent>
      <p>Add to library</p>
    </TooltipContent>
  </TooltipRoot>`}
/>

## API Reference

### Tooltip

| Prop                  | Type              | Default                                                                                              | Description                                                                                                                                                                            |
| --------------------- | ----------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content`             | `React.ReactNode` | -                                                                                                    | The content of the Tooltip                                                                                                                                                             |
| `isDisabled`          | `boolean`         | -                                                                                                    | Whether the tooltip should be disabled, independent from the trigger.                                                                                                                  |
| `delay`               | `number`          | 700                                                                                                  | The delay time for the tooltip to show up.                                                                                                                                             |
| `closeDelay`          | `number`          | 0                                                                                                    | The delay time for the tooltip to close.                                                                                                                                               |
| `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).                                                                                                                                 |
| `triggerRef`          | `boolean`         | `RefObject<Element>`                                                                                 | The ref for the element which the tooltip positions itself with respect to.<br/>When used within a TooltipTrigger this is set automatically. It is only required when used standalone. |
| `isEntering`          | `boolean`         | -                                                                                                    | Whether the tooltip is currently performing an entry animation.                                                                                                                        |
| `isExiting`           | `boolean`         | -                                                                                                    | Whether the tooltip is currently performing an exit animation.                                                                                                                         |
| `placement`           | `Placement`       | `'top'`                                                                                              | The placement of the element with respect to its anchor element.                                                                                                                       |
| `containerPadding`    | `number`          | `12`                                                                                                 | The placement padding that should be applied between the element and its surrounding container.                                                                                        |
| `offset`              | `number`          | `10`                                                                                                 | The additional offset applied along the main axis between the element and its anchor element.                                                                                          |
| `crossOffset`         | `number`          | `0`                                                                                                  | The additional offset applied along the cross axis between the element and its anchor element.                                                                                         |
| `shouldFlip`          | `boolean`         | `true`                                                                                               | Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely.                                     |
| `isOpen`              | `boolean`         | -                                                                                                    | Whether the element is rendered.                                                                                                                                                       |
| `defaultOpen`         | `boolean`         | -                                                                                                    | Whether the overlay is open by default (uncontrolled).                                                                                                                                 |
| `arrowBoundaryOffset` | `number`          | -                                                                                                    | The minimum distance the arrow's edge should be from the edge of the overlay element.                                                                                                  |
| `children`            | `boolean`         | `ReactNode \| (values: TooltipRenderProps & {defaultChildren: ReactNode \| undefined}) => ReactNode` | The children of the component. A function may be provided to alter the children based on component state.                                                                              |

| Event          | Type                        | Description                                                   |
| -------------- | --------------------------- | ------------------------------------------------------------- |
| `onOpenChange` | `(isOpen: boolean) => void` | Handler that is called when the overlay's open state changes. |

## Accessibility

### Keyboard interactions

| Key   | Description                                                                                         |
| ----- | --------------------------------------------------------------------------------------------------- |
| `Tab` | Tabbing into an item that has a tooltip associated with it (e.g., a button icon) shows the tooltip. |
| `Esc` | Hides the tooltip                                                                                   |
