npm package: @leafygreen-ui/tooltip
Description: LeafyGreen UI Kit Tooltip
Latest version: 14.3.1

# Tooltip

![npm (scoped)](https://img.shields.io/npm/v/@leafygreen-ui/tooltip.svg)

#### [View on MongoDB.design](https://www.mongodb.design/component/tooltip/live-example/)

## Installation

### PNPM

```shell
pnpm add @leafygreen-ui/tooltip
```

### Yarn

```shell
yarn add @leafygreen-ui/tooltip
```

### NPM

```shell
npm install @leafygreen-ui/tooltip
```

## Example

```js
import Tooltip from '@leafygreen-ui/tooltip';

<Tooltip
  align="top"
  justify="start"
  trigger={<button>trigger</button>}
  triggerEvent="hover"
  darkMode={true}
>
  I am an uncontrolled Tooltip!
</Tooltip>;
```

## Properties

| Prop              | Type                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Default                                     |
| ----------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `open`            | `boolean`                                 | Controls the component, and determines whether or not the `<Tooltip />` will appear open or closed.                                                                                                                                                                                                                                                                                                                                                                                                                                            | `false`                                     |
| `setOpen`         | `function`                                | If controlling the component, pass state handling function to setOpen prop. This will keep the consuming application's state in-sync with LeafyGreen's state, while the `<Tooltip />` component responds to events such as backdrop clicks and a user pressing the Escape key.                                                                                                                                                                                                                                                                 | `(boolean) => boolean`                      |
| `initialOpen`     | `boolean`                                 | Passes an initial "open" value to an uncontrolled Tooltip.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `false`                                     |
| `shouldClose`     | `function`                                | Callback that should return a boolean that determines whether or not the `<Tooltip />` should close when a user tries to close it.                                                                                                                                                                                                                                                                                                                                                                                                             | `() => true`                                |
| `align`           | `'top'`, `'bottom'`, `'left'`, `'right'`  | Determines the preferred alignment of the `<Tooltip />` component relative to the element passed to the `trigger` prop. If no `trigger` is passed, the Tooltip will be positioned against its nearest parent element.                                                                                                                                                                                                                                                                                                                          | `'top'`                                     |
| `justify`         | `'start'`, `'middle'`, `'end'`            | Determines the preferred justification of the `<Tooltip />` component (based on the alignment) relative to the element passed to the `trigger` prop. If no `trigger` is passed, the Tooltip will be positioned against its nearest parent element.                                                                                                                                                                                                                                                                                             | `'start'`                                   |
| `trigger`         | `function`, `React.ReactNode`             | A `React.ReactNode` against which the `<Tooltip />` will be positioned, and what will be used to trigger the opening and closing of the `Tooltip` component, when the `Tooltip` is uncontrolled. If no `trigger` is passed, the `Tooltip` will be positioned against its nearest parent element. If using a `ReactNode` or inline function, trigger signature is: ({children, ...rest}) => (<button {...rest}>trigger {children}</button>). When using a function, you must pass `children` as an argument in order for the tooltip to render. |                                             |
| `triggerEvent`    | `'hover'`, `'click'`                      | DOM event that triggers opening/closing of `<Tooltip />` component                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `'hover'`                                   |
| `darkMode`        | `boolean`                                 | Determines if the `<Tooltip />` will appear in dark mode.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `false`                                     |
| `id`              | `string`                                  | `id` applied to `<Tooltip />` component                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |                                             |
| `className`       | `string`                                  | Applies a className to Tooltip container                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |                                             |
| `children`        | `node`                                    | Content that will be rendered inside of `<Tooltip />`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |                                             |
| `enabled`         | `boolean`                                 | Enables Tooltip to trigger based on the event specified by `triggerEvent`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `true`                                      |
| `onClose`         | `function`                                | Callback that is called when the tooltip is closed internally. E.g. on ESC press, on backdrop click, on blur..                                                                                                                                                                                                                                                                                                                                                                                                                                 |                                             |
| `renderMode`      | `'inline'` \| `'portal'` \| `'top-layer'` | Options to render the popover element <br> \* [deprecated] `'inline'` will render the popover element inline in the DOM where it's written <br> \* [deprecated] `'portal'` will render the popover element in a new div appended to the body. Alternatively, can be portaled into a provided `portalContainer` <br> \* `'top-layer'` will render the popover element in the top layer                                                                                                                                                          | `'top-layer'`                               |
| `portalContainer` | `HTMLElement` \| `null`                   | Sets the container used for the popover's portal. NOTE: If using a `scrollContainer` make sure that the `portalContainer` is contained within the `scrollContainer`. E.g, passing the same refrence to `scrollContainer` and `portalContainer`.                                                                                                                                                                                                                                                                                                |                                             |
| `scrollContainer` | `HTMLElement` \| `null`                   | If the popover portal has a scrollable ancestor other than the window, this prop allows passing a reference to that lement to allow the portal to position properly.                                                                                                                                                                                                                                                                                                                                                                           |                                             |
| `portalClassName` | `string`                                  | Passes the given className to the popover's portal container if the default portal container is being used.                                                                                                                                                                                                                                                                                                                                                                                                                                    |                                             |
| `popoverZIndex`   | `number`                                  | Sets the z-index CSS property for the popover.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |                                             |
| `baseFontSize`    | `13` \| `16`                              | Allows consuming applications to override font-size as set by the LeafyGreen Provider. This prop is only considered when `variant` is `'default'`.                                                                                                                                                                                                                                                                                                                                                                                             | default to value set by LeafyGreen Provider |
| `variant`         | `'default'` \| `'compact'`                | Variant of the tooltip to be rendered.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `'default'`                                 |
| ...               | native `div` attributes                   | Any other props will be spread on the root `div` element                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |                                             |

### External tooltip triggers

When defining a tooltip trigger as a separate element, ensure the `refEl` is defined on the `<Tooltip>` element, and use the `useTooltipTriggerEventHandlers` hook to create tooltip event handlers.

```tsx
const triggerRef = useRef();
const [open, setOpen] = useState(false);
const tooltipEventHandlers = useTooltipTriggerEventHandlers({
  triggerEvent: TriggerEvent.Hover,
  setState: setOpen,
  onFocus: e => {
    console.log(e);
  }, // side effects called on focus of the trigger
});

return (
  <>
    <Button ref={triggerRef} {...tooltipEventHandlers}>
      Button
    </Button>
    <Tooltip refEl={triggerRef} open={open} setOpen={setOpen}>
      Content
    </Tooltip>
  </>
);
```