> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Tooltip
> Show supplementary information when a trigger is hovered or focused.
export const StoryEmbed = ({storyId, title, height = 240}) => <>
Open in Storybook
;
Use `Tooltip` for a short explanation of a control or truncated text. Keep essential information visible, give controls an accessible name, and use [Popover](/ui/primitives/surfaces/popover) when the content contains links, buttons, or other controls.
## Single trigger
```tsx theme={null}
import { Button } from 'twenty-ui/primitives/input';
import { Tooltip } from 'twenty-ui/primitives/surfaces';
export const ExportHelp = () => (
);
```
The convenience component accepts one trigger element as `children`. Native elements receive the trigger attributes, event handlers, and ref directly. Custom trigger components must forward all of them. A wrapper element also works with a component that does not forward every trigger prop.
Hover opens the tooltip after `delay` milliseconds, which defaults to `600`. Keyboard focus opens it immediately. `closeDelay` defaults to `0`; hovering over the popup keeps it open unless `disableHoverablePopup` is set. Escape dismisses it.
## Controlled state
Use `open` and `onOpenChange` together when the application owns visibility. Use `defaultOpen` only to set the initial visibility of an uncontrolled tooltip.
```tsx theme={null}
import { useState } from 'react';
import { Button } from 'twenty-ui/primitives/input';
import { Tooltip } from 'twenty-ui/primitives/surfaces';
export const ControlledExportHelp = () => {
const [open, setOpen] = useState(false);
return (
);
};
```
## Rich content and composition
`Tooltip.Content` provides a title, optional description, and optional leading icon. Use it as `content` or inside `Tooltip.Popup`.
```tsx theme={null}
import { IconInfoCircle } from 'twenty-ui/icon';
import { Button } from 'twenty-ui/primitives/input';
import { Tooltip } from 'twenty-ui/primitives/surfaces';
export const ExportDetails = () => (
}>
}
description="Only the records matching your current filters are included."
>
Export visible records
);
```
| Part | Purpose |
| ---------- | ------------------------------------------------------------- |
| `Root` | Coordinates visibility and trigger interactions. |
| `Trigger` | Renders the element that opens the tooltip on hover or focus. |
| `Popup` | Renders positioned content in a portal. |
| `Content` | Styles primary text, a description, and an icon. |
| `Provider` | Coordinates opening delays across a group of tooltips. |
`Tooltip.createHandle()` connects detached triggers to a shared `Root` through their `handle` prop. Keep each popup's content supplementary even when several triggers share it.
## Disabled controls
Native disabled buttons cannot receive keyboard focus. Wrap one in a focusable trigger so users can discover why the action is unavailable.
```tsx theme={null}
import { Button } from 'twenty-ui/primitives/input';
import { Tooltip } from 'twenty-ui/primitives/surfaces';
export const UnavailableExport = () => (
);
```
Setting `disabled` on `Tooltip` suppresses the tooltip itself. It does not disable the control.
## Placement and overflowing text
The popup defaults to `side="top"`, `align="center"`, `sideOffset={10}`, and a maximum width of `300` pixels. Placement adjusts to available space. Use `arrow` for an arrow and `container` to override the theme's portal destination; see [theming](/ui/theming).
Use `OverflowingTextWithTooltip` when a text label should show its full value only when truncated. Its existing `text`, `tooltipContent`, and `tooltipPlace` props remain available.
## Props
The reference is generated from the public component types. Native popup attributes and event handlers are also accepted.
A ref to imperative actions.
* `unmount`: Unmounts the tooltip popup.
* `close`: Closes the tooltip imperatively when called.
Alignment relative to the trigger. Defaults to center.
Offset along the alignment axis in pixels.
An explicit positioning anchor for the popup.
Displays an arrow pointing to the trigger. Defaults to false.
A single trigger element. Custom components must forward their ref, native attributes, and event handlers.
Additional CSS class for the popup.
Delay in milliseconds before closing after hover ends. Defaults to 0.
Whether the tooltip should close when this trigger is clicked.
Determines how to handle collisions when positioning the popup.
`side` controls overflow on the preferred placement axis (`top`/`bottom` or `left`/`right`):
* `'flip'`: keep the requested side when it fits; otherwise try the opposite side
(`top` and `bottom`, or `left` and `right`).
* `'shift'`: never change side; keep the requested side and move the popup within
the clipping boundary so it stays visible.
* `'none'`: do not correct side-axis overflow.
`align` controls overflow on the alignment axis (`start`/`center`/`end`):
* `'flip'`: keep side, but swap `start` and `end` when the requested alignment overflows.
* `'shift'`: keep side and requested alignment, then nudge the popup along the
alignment axis to fit.
* `'none'`: do not correct alignment-axis overflow.
`fallbackAxisSide` controls fallback behavior on the perpendicular axis when the
preferred axis cannot fit:
* `'start'`: allow perpendicular fallback and try the logical start side first
(`top` before `bottom`, or `left` before `right` in LTR).
* `'end'`: allow perpendicular fallback and try the logical end side first
(`bottom` before `top`, or `right` before `left` in LTR).
* `'none'`: do not fallback to the perpendicular axis.
When `side` is `'shift'`, explicitly setting `align` only supports `'shift'` or `'none'`.
If `align` is omitted, it defaults to `'flip'`.
An element or a rectangle that delimits the area that the popup is confined to.
Additional space to maintain from the edge of the collision boundary.
Portal destination. Defaults to the current theme container.
Supplementary content displayed in the tooltip.
Initial visibility when the tooltip manages its own state.
ID of the trigger that the tooltip is associated with.
This is useful in conjunction with the `defaultOpen` prop to create an initially open tooltip.
Delay in milliseconds before opening on hover. Defaults to 600.
Whether to disable the popup from tracking any layout shift of its positioning anchor.
Prevents the tooltip from opening.
Prevents hovering over the popup from keeping it open.
Keeps the popup mounted while closed.
Maximum popup width. Defaults to 300 pixels.
Called when an interaction requests a visibility change.
Event handler called after any animations complete when the tooltip is opened or closed.
Controlled visibility of the tooltip.
CSS positioning method for the popup.
Allows you to replace the component's HTML element
with a different tag, or compose it with another component.
Accepts a `ReactElement` or a function that returns the element to render.
Preferred side of the trigger. Defaults to top and may change to avoid collisions.
Distance from the trigger in pixels. Defaults to 10.
Whether to maintain the popup in the viewport after
the anchor element was scrolled out of view.
Inline styles for the popup.
Determines which axis the tooltip should track the cursor on.
ID of the trigger that the tooltip is associated with.
This is useful in conjunction with the `open` prop to create a controlled tooltip.
There's no need to specify this prop when the tooltip is uncontrolled (that is, when the `open` prop is not set).
### Tooltip.Root
A ref to imperative actions.
* `unmount`: Unmounts the tooltip popup.
* `close`: Closes the tooltip imperatively when called.
The content of the tooltip.
This can be a regular React node or a render function that receives the `payload` of the active trigger.
Whether the tooltip is initially open.
To render a controlled tooltip, use the `open` prop instead.
ID of the trigger that the tooltip is associated with.
This is useful in conjunction with the `defaultOpen` prop to create an initially open tooltip.
Whether the tooltip is disabled.
Whether the tooltip contents can be hovered without closing the tooltip.
A handle to associate the tooltip with a trigger.
If specified, allows external triggers to control the tooltip's open state.
Can be created with the Tooltip.createHandle() method.
Event handler called when the tooltip is opened or closed.
Event handler called after any animations complete when the tooltip is opened or closed.
Whether the tooltip is currently open.
Determines which axis the tooltip should track the cursor on.
ID of the trigger that the tooltip is associated with.
This is useful in conjunction with the `open` prop to create a controlled tooltip.
There's no need to specify this prop when the tooltip is uncontrolled (that is, when the `open` prop is not set).
### Tooltip.Trigger
CSS class applied to the element, or a function that
returns a class based on the component's state.
How long to wait before closing the tooltip. Specified in milliseconds.
Whether the tooltip should close when this trigger is clicked.
How long to wait before opening the tooltip on hover. Specified in milliseconds.
If `true`, the tooltip will not open when interacting with this trigger.
Note that this doesn't apply the `disabled` attribute to the trigger element.
If you want to disable the trigger element itself, you can pass the `disabled` prop to the trigger element via the `render` prop.
A handle to associate the trigger with a tooltip.
A payload to pass to the tooltip when it is opened.
Allows you to replace the component's HTML element
with a different tag, or compose it with another component.
Accepts a `ReactElement` or a function that returns the element to render.
Style applied to the element, or a function that
returns a style object based on the component's state.
### Tooltip.Popup
Alignment relative to the trigger. Defaults to center.
Offset along the alignment axis in pixels.
An explicit positioning anchor for the popup.
Displays an arrow pointing to the trigger. Defaults to false.
Additional CSS class for the popup.
Determines how to handle collisions when positioning the popup.
`side` controls overflow on the preferred placement axis (`top`/`bottom` or `left`/`right`):
* `'flip'`: keep the requested side when it fits; otherwise try the opposite side
(`top` and `bottom`, or `left` and `right`).
* `'shift'`: never change side; keep the requested side and move the popup within
the clipping boundary so it stays visible.
* `'none'`: do not correct side-axis overflow.
`align` controls overflow on the alignment axis (`start`/`center`/`end`):
* `'flip'`: keep side, but swap `start` and `end` when the requested alignment overflows.
* `'shift'`: keep side and requested alignment, then nudge the popup along the
alignment axis to fit.
* `'none'`: do not correct alignment-axis overflow.
`fallbackAxisSide` controls fallback behavior on the perpendicular axis when the
preferred axis cannot fit:
* `'start'`: allow perpendicular fallback and try the logical start side first
(`top` before `bottom`, or `left` before `right` in LTR).
* `'end'`: allow perpendicular fallback and try the logical end side first
(`bottom` before `top`, or `right` before `left` in LTR).
* `'none'`: do not fallback to the perpendicular axis.
When `side` is `'shift'`, explicitly setting `align` only supports `'shift'` or `'none'`.
If `align` is omitted, it defaults to `'flip'`.
An element or a rectangle that delimits the area that the popup is confined to.
Additional space to maintain from the edge of the collision boundary.
Portal destination. Defaults to the current theme container.
Whether to disable the popup from tracking any layout shift of its positioning anchor.
Keeps the popup mounted while closed.
Maximum popup width. Defaults to 300 pixels.
CSS positioning method for the popup.
Allows you to replace the component's HTML element
with a different tag, or compose it with another component.
Accepts a `ReactElement` or a function that returns the element to render.
Preferred side of the trigger. Defaults to top and may change to avoid collisions.
Distance from the trigger in pixels. Defaults to 10.
Whether to maintain the popup in the viewport after
the anchor element was scrolled out of view.
Inline styles for the popup.
### Tooltip.Content
Secondary explanation beneath the primary text.
Allows you to replace the component's HTML element
with a different tag, or compose it with another component.
Accepts a `ReactElement` or a function that returns the element to render.
An icon displayed before the text.
### Tooltip.Provider
How long to wait before closing a tooltip. Specified in milliseconds.
How long to wait before opening the tooltip on hover. Specified in milliseconds.
Another tooltip will open instantly if the previous tooltip
is closed within this timeout. Specified in milliseconds.