# Tooltip
> Tooltip is used to describe or add additional information to the user.

## Import

```js
import { Tooltip } from '@gemini-suite/vera-react';
```

## Examples

### Basic

<Callout variant="important">

If the `Tooltip` is wrapping a functional component, ensure that the functional component accepts a `ref` using `forwardRef`.

</Callout>

```jsx
<Tooltip content={'Tooltip content'}>
  <Text>{'I have a tooltip, hover me'}</Text>
</Tooltip>
```

### Formatted content

Tooltip accepts any valid React node as content.

```jsx
<Tooltip
  placement="top"
  content={
    <Flex gap="spacingS">
      <SvgIcon iconName="download" />
      <Box>
        {'Tooltip with'} <b>{'icon'}</b>
      </Box>
    </Flex>
  }
>
  <Text>{'I have a tooltip, hover me'}</Text>
</Tooltip>
```

### Sizes

`Tooltip` component comes in two sizes: `medium` and `small`. By default, it uses `medium` size.

```jsx
<Flex flow="column" cross="start">
  <Tooltip content={'Tooltip content'} size="small" placement="right">
    <Text>{'I have a small tooltip'}</Text>
  </Tooltip>
  <Tooltip content={'Tooltip content'} placement="right">
    <Text>{'I have a medium tooltip'}</Text>
  </Tooltip>
</Flex>
```

### Placement

Tooltip uses [Positioner](/components/utility/positioner) under the hood, so you can control its `placement`:

```jsx
<Flex>
  <Tooltip placement="right" content="Right tooltip">
    <Button variant="outline">{'Button'}</Button>
  </Tooltip>
  <Tooltip placement="top_left" content="Top-left tooltip">
    <SvgIcon
      size="medium"
      iconName="user"
      css={{ color: '$foregroundAccentModerate' }}
    />
  </Tooltip>
</Flex>
```

### Long content wrapping

Use the `maxWidth` prop to control how long content wraps within the tooltip.

```jsx
<Flex>
  <Tooltip
    content="This is a very long tooltip content that will wrap at the default width of 45 characters"
    placement="top"
  >
    <Button variant="outline">Default width</Button>
  </Tooltip>
  <Tooltip
    content="This is a very long tooltip content that will wrap at a custom width"
    maxWidth="20ch"
    placement="top"
  >
    <Button variant="outline">Narrow width</Button>
  </Tooltip>
</Flex>
```

### Controlled tooltip

You can make the dialog controlled, by passing your own state to `isOpen` prop.

```jsx
() => {
  const [showTooltip, setShowTooltip] = React.useState(false);

  return (
    <React.Fragment>
      <Flex flow="column">
        <Box>
          <Tooltip
            placement="top"
            isOpen={showTooltip}
            content={'Tooltip content'}
          >
            <span>{'I have a tooltip controlled by buttons below'}</span>
          </Tooltip>
        </Box>
        <Flex>
          <Button variant="outline" onClick={() => setShowTooltip(true)}>
            {'Open tooltip'}
          </Button>
          <Button variant="outline" onClick={() => setShowTooltip(false)}>
            {'Close tooltip'}
          </Button>
        </Flex>
      </Flex>
    </React.Fragment>
  );
};
```

### Disabled tooltip

You can disable showing the tooltip with `isDisabled` prop. Also, if there is no content provided, tooltip will skip rendering.

```jsx
<Flex>
  <Tooltip isDisabled>
    <span>{'Disabled tooltip 😭'}</span>
  </Tooltip>
  <Tooltip>
    <span>{'No tooltip content 😭'}</span>
  </Tooltip>
</Flex>
```

### Close on click

```jsx
<Flex>
  <Tooltip content={'Tooltip content'}>
    <Button variant="outline">{'Will close on click'}</Button>
  </Tooltip>
  <Tooltip content={'Tooltip content'} shouldCloseOnClick={false}>
    <Button variant="outline">{'Will not close on click'}</Button>
  </Tooltip>
</Flex>
```

### Delayed open

The `delay` prop controls how long to wait before showing a tooltip on hover.

Choose the appropriate delay based on how critical the information is and how frequently users need it:

- **600ms (default)** - For most tooltips on standard interactive elements; reduces accidental tooltips when moving the cursor (no need to specify the `delay` prop)
- **300ms (fast)** - For interactive elements where quick context is helpful (toolbar actions, status indicators, abbreviated labels)
- **0ms (instant)** - For elements whose primary purpose is to provide information that users need immediately (info icons, help buttons)

```jsx
<Flex>
  <Tooltip content={'Supplementary information'}>
    <Button variant="outline">{'Default'}</Button>
  </Tooltip>
  <Tooltip content={'Copy to clipboard'} delay={300}>
    <Button variant="outline" withLoneIcon>
      <SvgIcon iconName="copy" />
    </Button>
  </Tooltip>
  <Tooltip content={'Instant help'} delay={0}>
    <Button variant="outline" leftIcon={<SvgIcon iconName="info" />}>
      {'Help'}
    </Button>
  </Tooltip>
</Flex>
```

### Delayed close

```jsx
<Tooltip content={'Tooltip content'} closeDelay={1000}>
  <Button variant="outline">{'Will close after 1s'}</Button>
</Tooltip>
```

---

## API Reference

| Name                 | Type                                                                                                     | Default    | Description                                                      | Required |
| -------------------- | -------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------- | -------- |
| `children`           | `React.ReactNode`                                                                                        |            | The React node to use as the trigger for the tooltip.            | Yes      |
| `content`            | `React.ReactNode`                                                                                        |            | The content of the tooltip.                                      |          |
| `isOpen`             | `boolean`                                                                                                | `false`    | The controlled open state of the tooltip.                        |          |
| `placement`          | `"top" \| "top_left" \| "top_right" \| "bottom" \| "bottom_left" \| "bottom_right" \| "left" \| "right"` | `"bottom"` | Placement of the tooltip. Smart positioning might override this. |          |
| `size`               | `"small" \| "medium"`                                                                                    | `"medium"` | Size of the tooltip.                                             |          |
| `anchorOffset`       | `number`                                                                                                 |            | Distance from the trigger to the tooltip.                        |          |
| `delay`              | `number`                                                                                                 | `600`      | Delay (in ms) before showing the tooltip.                        |          |
| `closeDelay`         | `number`                                                                                                 |            | Delay (in ms) before hiding the tooltip.                         |          |
| `isDisabled`         | `boolean`                                                                                                | `false`    | When `true`, the tooltip will not show up.                       |          |
| `shouldCloseOnClick` | `boolean`                                                                                                | `true`     | When `true`, the tooltip will close on click.                    |          |
| `onClose`            | `() => void`                                                                                             |            | Event handler called when the tooltip closes.                    |          |
| `onOpen`             | `() => void`                                                                                             |            | Event handler called when the tooltip opens.                     |          |
| `addAriaDescription` | `boolean`                                                                                                | `true`     | When `true`, describes the element with the tooltip content.     |          |
| `maxWidth`           | `StitchesCss['width']`                                                                                   | `45ch`     | Maximum width of the tooltip content before wrapping.            |          |