# Tooltip

A component that displays additional information on hover.

## Import

```tsx
import { Tooltip } from '@coinbase/cds-web/overlays/Tooltip'
```

## Examples

### Placement

```jsx live
function TooltipPlacement() {
  const content = 'This is the tooltip Content';
  return (
    <HStack spacingHorizontal={2} gap={2} justifyContent="space-around">
      <Tooltip content={content}>
        <Button>Default</Button>
      </Tooltip>
      <Tooltip content={content} placement="top">
        <Button>Top</Button>
      </Tooltip>
      <Tooltip content={content} placement="left">
        <Button>Left</Button>
      </Tooltip>
      <Tooltip content={content} placement="right">
        <Button>Right</Button>
      </Tooltip>
      <Tooltip content={content} placement="bottom">
        <Button>Bottom</Button>
      </Tooltip>
    </HStack>
  );
}
```

### Positioning

Sometimes you may want to use a tooltip with an absolute positioned element.

To ensure the tooltip is properly aligned, you should instead set the position prop on the tooltip.

```jsx live
function TooltipPosition() {
  const content = 'This is the tooltip Content';
  return (
    <VStack gap={2}>
      <Box position="relative">
        Set your default display currency.
        <Tooltip content="I am not centered horizontally">
          <Icon active color="fg" name="info" paddingStart={1} position="absolute" />
        </Tooltip>
      </Box>
      <Box position="relative">
        Set your default display currency.
        <Tooltip content="I am centered horizontally" position="absolute">
          <Icon active color="fg" name="info" paddingStart={1} />
        </Tooltip>
      </Box>
    </VStack>
  );
}
```

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `content` | `null \| string \| number \| false \| true \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal` | Yes | `-` | The content to render within the tooltip. |
| `autoFocusDelay` | `number` | No | `undefined` | The amount of time in milliseconds to wait before auto-focusing the first focusable element. |
| `disableAutoFocus` | `boolean` | No | `false` | If true, the focus trap will not automatically shift focus to itself when it opens, and replace it to the last focused element when it closes. |
| `disableFocusTrap` | `boolean` | No | `-` | Disables the focus trap to allow normal keyboard navigation. |
| `disablePortal` | `boolean` | No | `false` | - |
| `disableTypeFocus` | `boolean` | No | `-` | Use for editable Search Input components to ensure focus is correctly applied |
| `elevation` | `0 \| 1 \| 2` | No | `-` | Determines a components shadow styles. Parent should have overflow set to visible to ensure styles are not clipped. |
| `focusTabIndexElements` | `boolean` | No | `false` | If true, the focus trap will include all elements with tabIndex values in the list of focusable elements. |
| `gap` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 0.25 \| 0.5 \| 0.75 \| 1.5` | No | `1` | This value corresponds to how big the gap between the subject and the tooltip is. We do not encourage usage of this prop. But it is enabled for special cases as an escape hatch. |
| `invertColorScheme` | `boolean` | No | `true` | Invert the themes activeColorScheme for this component |
| `placement` | `top \| bottom \| left \| right` | No | `top` | Position of tooltip in relation to the subject. |
| `respectNegativeTabIndex` | `boolean` | No | `false` | If true, the focus trap will respect negative tabIndex values, removing them from the list of focusable elements. |
| `testID` | `string` | No | `-` | Used to locate this element in unit and end-to-end tests. Under the hood, testID translates to data-testid on Web. On Mobile, testID stays the same - testID |
| `tooltipId` | `string` | No | `-` | A unique ID used to ensure tooltips are accessible |
| `visible` | `boolean` | No | `true` | Control whether the tooltip is shown or hidden. |
| `zIndex` | `number` | No | `4` | Typically only used when disablePortal is set to true to adjust zIndex of tooltip. When using portal this value should remain as default. |