# Core/Tooltip - Usage

A component to display additional information when hovering or focusing on an interactive element.

## Custom Triggers

:::warning

**Custom triggers are an advanced feature and should be used with caution.** Tooltips should wrap interactive
elements. The defaults provided in Capra ensure an accessible experience. When using custom triggers, the dev assumes
responsibility for ensuring the tooltip trigger is accessible.

:::

By default, tooltips are triggered on for the `Button`, `IconButton`, `Link`, or `ButtonLink` components. For other elements, you can wrap them in a `CustomTooltipTrigger` to allow hover and focus to open the tooltip. The trigger still needs an appropriate ARIA role or semantic HTML element, and custom components should forward refs via `forwardRef` as well as spread props onto the underlying DOM node.

```tsx
import { Tooltip, CustomTooltipTrigger } from '@capra/core';

function MyComponent() {
  retur(
    <Tooltip title="Tooltip content">
      <CustomTooltipTrigger>
        <span role="button" tabIndex={0} style={{ cursor: 'default', textDecoration: 'underline' }}>
          Custom trigger (span)
        </span>
      </CustomTooltipTrigger>
    </Tooltip>,
  );
}
```

**Important Notes**

* The trigger element must have an appropriate ARIA role or semantic HTML element.
* `CustomTooltipTrigger` only accepts a single child.

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `React.ReactNode` | Yes | `--` | The visible trigger element. This can be a single element or a component tree, but there MUST be a focusable element (`Button`, `IconButton`, `Link`, or a custom trigger via `CustomTooltipTrigger`) in the tree. Nothing else will trigger the tooltip. |
| `title` | `string` | Yes | `--` | The content of the tooltip. |
| `shortcut` | `string` | No | `--` | Optional keyboard shortcut label shown next to the title (e.g. `⌘K`, `Ctrl+S`). |
| `placement` | `(typeof placements)[number]` | No | 'bottom' | The position of the tooltip relative to the trigger element.<br>@default 'bottom' |
| `isDisabled` | `boolean` | No | false | Whether the tooltip is disabled.<br>@default false |
| `getContainer` | `() => HTMLElement \| null` | No | `--` | The container to mount the tooltip in.<br>@default document.body<br><br>**Warning**: This is an unsafe feature and may cause accessibility, keyboard navigation, and other issues. Only use if you know what you are doing. |
| `className` | `never` | No | `--` | Use `FORCE__className` instead. |
| `style` | `never` | No | `--` | Inline styles are not supported; use component props or `FORCE__className`. |
| `FORCE__className` | `string` | No | `--` | 🚨 This prop is meant to be an escape hatch. 🚨<br><br>If the desired style cannot be achieved using component props, use this as a last resort. The inner workings of Capra components are implementation details and this escape hatch gives one access to those implementation details. We cannot make any guarantees that styles will applied correctly across version updates. Please use it responsibly.<br><br>Add a CSS class to the component. |