# Tooltip

- Page: https://jiguang132.com/resources/ant-design/docs/tooltip
- Resource: Ant Design (https://jiguang132.com/resources/ant-design.md)
- All guides: https://jiguang132.com/resources/ant-design/docs.md

Simple text popup box.


## When To Use

- The tip is shown on mouse enter, and is hidden on mouse leave. The Tooltip doesn't support complex text or operations.
- To provide an explanation of a `button/text/operation`. It's often used instead of the html `title` attribute.

## Examples


- Basic · `basic`
- Smooth Transition · `smooth-transition`
- Placement · `placement`
- Arrow · `arrow`
- Auto Shift · `shift`

- Realign after layout changes · `force-align`

- Colorful Tooltip · `colorful`


- Disabled · `disabled`

- Wrap custom component · `wrap-custom-component`
- Custom semantic dom styling · `style-class`

## API

Common props ref：[Common props](#jguang-common-props)

| Property | Description | Type | Default | Version | [Global Config](/components/config-provider#component-config) |
| --- | --- | --- | --- | --- | --- |
| title | The text shown in the tooltip | ReactNode \| () => ReactNode | - | - | × |
| color | The background color. After using this attribute, the internal text color will adapt automatically | string | - | 5.27.0 | × |
| classNames | Semantic DOM class | Record<[SemanticDOM](#semantic-dom), string> \| (info: { props }) => Record<[SemanticDOM](#semantic-dom), string> | - | 5.23.0 | 5.23.0 |
| styles | Semantic DOM style | Record<[SemanticDOM](#semantic-dom), CSSProperties> \| (info: { props }) => Record<[SemanticDOM](#semantic-dom), CSSProperties> | - | 5.23.0 | 5.23.0 |

### Common API

<Antd component="Alert" title="The following APIs are shared by Tooltip, Popconfirm, Popover." type="info" banner="true"></Antd>


| Property | Description | Type | Default | Version | [Global Config](/components/config-provider#component-config) |
| --- | --- | --- | --- | --- | --- |
| align | Please refer to the settings [dom-align](https://github.com/yiminghe/dom-align) | object | - |  | × |
| arrow | Change arrow's visible state and change whether the arrow is pointed at the center of target. | boolean \| { pointAtCenter: boolean } | true | 5.2.0 | Tooltip: 6.0.0, Popover: 6.0.0, Popconfirm: 6.0.0 |
| autoAdjustOverflow | Whether to adjust popup placement automatically when popup is off screen | boolean | true |  | × |
| color | The background color | string | - | 4.3.0 | × |
| classNames | Customize class for each semantic structure inside the component. Supports object or function. | Record<[SemanticDOM](#semantic-dom), string> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), string> | - | 5.23.0 | Tooltip: 5.23.0, Popover: 5.23.0, Popconfirm: 5.23.0 |
| defaultOpen | Whether the floating tooltip card is open by default | boolean | false | 4.23.0 | × |
| ~~destroyTooltipOnHide~~ | Whether destroy dom when close | boolean | false |  | × |
| destroyOnHidden | Whether destroy dom when close | boolean | false | 5.25.0 | × |
| fresh | Tooltip will cache content when it is closed by default. Setting this property will always keep updating | boolean | false | 5.10.0 | × |
| getPopupContainer | The DOM container of the tip, the default behavior is to create a `div` element in `body` | (triggerNode: HTMLElement) => HTMLElement | () => document.body |  | × |
| mouseEnterDelay | Delay in seconds, before tooltip is shown on mouse enter | number | 0.1 |  | Tooltip: 6.6.0, Popover: 6.6.0, Popconfirm: 6.6.0 |
| mouseLeaveDelay | Delay in seconds, before tooltip is hidden on mouse leave | number | 0.1 |  | Tooltip: 6.6.0, Popover: 6.6.0, Popconfirm: 6.6.0 |
| ~~overlayClassName~~ | Class name of the tooltip card, please use `classNames.root` instead | string | - |  | × |
| ~~overlayStyle~~ | Style of the tooltip card, please use `styles.root` | React.CSSProperties | - |  | × |
| ~~overlayInnerStyle~~ | Style of the tooltip inner content, please use `styles.container` instead | React.CSSProperties | - |  | × |
| placement | The position of the tooltip relative to the target, which can be one of `top` `left` `right` `bottom` `topLeft` `topRight` `bottomLeft` `bottomRight` `leftTop` `leftBottom` `rightTop` `rightBottom` | string | `top` |  | × |
| styles | Customize inline style for each semantic structure inside the component. Supports object or function. | Record<[SemanticDOM](#semantic-dom), CSSProperties> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), CSSProperties> | - | 5.23.0 | Tooltip: 5.23.0, Popover: 5.23.0, Popconfirm: 5.23.0 |
| trigger | Tooltip trigger mode. Could be multiple by passing an array | `hover` \| `focus` \| `click` \| `contextMenu` \| Array&lt;string> | `hover` |  | Tooltip: 6.1.0, Popover: 6.1.0, Popconfirm: 6.1.0 |
| open | Whether the floating tooltip card is open or not. Use `visible` under 4.23.0 ([why?](/docs/react/faq#why-open)) | boolean | false | 4.23.0 | × |
| zIndex | Config `z-index` of Tooltip | number | - |  | × |
| onOpenChange | Callback executed when visibility of the tooltip card is changed | (open: boolean) => void | - | 4.23.0 | × |


### ConfigProvider - tooltip.unique {#config-provider-tooltip-unique}

You can configure global unique display for Tooltip through ConfigProvider. When `unique` is set to `true`, only one Tooltip under the ConfigProvider will be displayed at the same time, providing better user experience and smooth transition effects.

Note: After configuration, properties like `getContainer`, `arrow` etc. will be ignored.

```tsx
import { Button, ConfigProvider, Space, Tooltip } from 'antd';

export default () => (
  <ConfigProvider
    tooltip={{
      unique: true,
    }}
  >
    <Space>
      <Tooltip title="First tooltip">
        <Button>Button 1</Button>
      </Tooltip>
      <Tooltip title="Second tooltip">
        <Button>Button 2</Button>
      </Tooltip>
    </Space>
  </ConfigProvider>
);
```

## Semantic DOM

| Semantic node | Native description | Version |
| --- | --- | --- |
| `root` | Root element (including arrows, content elements) with absolute positioning, z-index, block display, max width, visibility, transform origin and arrow background color | — |
| `container` | Content element with min width and height, padding, color, text alignment, background color, border radius, shadow and border styles | — |
| `arrow` | Arrow element with width, height, position, color and border styles | — |

Semantic description source: `vendor/components/tooltip/demo/_semantic.tsx`

## Design Token

Types, inheritance and declarations retain the pinned native source. Defaults are computed by the native theme and may be overridden by ConfigProvider; this table does not invent static defaults.

| Token | Type | Native description |
| --- | --- | --- |
| `maxWidth` | `number` | Max width of tooltip |
| `zIndexPopup` | `number` | z-index of tooltip |

Declaration source: `vendor/components/tooltip/style/index.ts`

```ts
import { unit } from '@ant-design/cssinjs';

import type { CSSObject } from '@ant-design/cssinjs';

import { resetComponent } from '../../style';

import { initFadeMotion, initZoomMotion } from '../../style/motion';

import type { ArrowOffsetToken } from '../../style/placementArrow';

import getArrowStyle, {
  getArrowOffsetToken,
  MAX_VERTICAL_CONTENT_RADIUS,
} from '../../style/placementArrow';

import type { ArrowToken } from '../../style/roundedArrow';

import { getArrowToken } from '../../style/roundedArrow';

import type { FullToken, GenerateStyle, GetDefaultToken } from '../../theme/internal';

import { genPresetColor, genStyleHooks, mergeToken } from '../../theme/internal';

import { genCssVar } from '../../theme/util/genStyleUtils';

export interface ComponentToken extends ArrowOffsetToken, ArrowToken {
  /**
   * @since 6.2.0
   * @desc 文字提示最大宽度
   * @descEN Max width of tooltip
   */
  maxWidth: number;
  /**
   * @desc 文字提示 z-index
   * @descEN z-index of tooltip
   */
  zIndexPopup: number;
}

interface TooltipToken extends FullToken<'Tooltip'> {
  // default variables
  tooltipMaxWidth: number;
  tooltipColor: string;
  tooltipBg: string;
  tooltipBorderRadius: number;
}
```

## FAQ

### Why doesn't HOC work sometimes? {#faq-hoc-component}

Please ensure that the child elements of `Tooltip` can accept `onMouseEnter`, `onMouseLeave`, `onPointerEnter`, `onPointerLeave`, `onFocus`, `onClick` events.

Please refer to https://github.com/ant-design/ant-design/issues/15909

### Why Tooltip not update content when close? {#faq-content-not-update}

Tooltip will cache content when it is closed to avoid flicker when content is updated:

```jsx
// `title` will not blink when `user` is empty
<Tooltip open={user} title={user?.name} />
```

<div>
<img alt="no blink" height="50" src="https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*KVx7QLOYwVsAAAAAAAAAAAAADrJ8AQ/original" />
</div>

If need update content when close, you can set `fresh` property ([#44830](https://github.com/ant-design/ant-design/issues/44830)):

```jsx
<Tooltip open={user} title={user?.name} fresh />
```

<div>
<img alt="no blink" height="50" src="https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*rUbsR4xWpMsAAAAAAAAAAAAADrJ8AQ/original" />
</div>

### Why doesn't Tooltip realign after a layout change? {#faq-force-align}

Tooltip does not continuously monitor all external layout changes by default, avoiding extra overhead for every open Tooltip. When async data loading, list refreshes, or expanding and collapsing regions changes the trigger element's position, get the `TooltipRef` through `ref` and call `forceAlign` after the layout update (see [#57809](https://github.com/ant-design/ant-design/issues/57809)). See the “Realign after layout changes” demo above for a complete example.

---



<Antd component="Alert" title="The following FAQ applies to Tooltip, Popconfirm, Popover components." type="warning" banner="true"></Antd>

### Why does the warning `findDOMNode is deprecated` sometimes appear in strict mode?

This is due to the implementation of `@rc-component/trigger`. `@rc-component/trigger` forces children to accept ref, otherwise it will fall back to findDOMNode, so children need to be native html tags. If not, you need to use `React.forwardRef` transparently passes `ref` to native html tags.

- `findDOMNode is deprecated` reproduce: <https://codesandbox.io/p/sandbox/finddomnode-c5hy96>
- Using `forwardRef` to fix: <https://codesandbox.io/p/sandbox/no-finddomnode-warning-forked-gdxczs>

### Why is the tooltip for my custom component not opening?

Similar issues: [#15909](https://github.com/ant-design/ant-design/issues/15909), [#12812](https://github.com/ant-design/ant-design/issues/12812).

Please ensure that the child node to accept `onMouseEnter`, `onMouseLeave`, `onPointerEnter`, `onPointerLeave`, `onFocus`, and `onClick` events, If you create your own component and do not explicitly add these mouse and pointer events as props, the tooltip will never appear. [See Example](/components/tooltip#tooltip-demo-wrap-custom-component).

### What's the placement logic?

It will follow `placement` config when screen has enough space. And flip when space is not enough (Such as `top` to `bottom` or `topLeft` to `bottomLeft`). Single direction such as `top` `bottom` `left` `right` will auto shift on the view:

<img alt="shift" height="200" src="https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*sxaTTJjLtIMAAAAAAAAAAAAADrJ8AQ/original" />

When `placement` is set to edge align such as `topLeft` `bottomRight`, it will only do flip but not do shift.

### How to support keyboard accessibility?

By default, Tooltip and similar components trigger on `hover` rather than `focus`, so they will not respond to keyboard focus events. If you want the component to support keyboard accessibility, you can enable it in the following ways:

- **Enable for a single component**: Set the `trigger` property to include `focus`, for example `trigger="focus"` or `trigger={['hover', 'focus']}`.
- **Enable globally**: Use `ConfigProvider` to set global configuration, so all relevant components across your application support keyboard focus trigger by default.

```jsx
import { ConfigProvider, Tooltip, Button } from 'antd';

// Single component
<Tooltip trigger={['hover', 'focus']} title="Title">
  <Button>Button</Button>
</Tooltip>

// Global configuration
<ConfigProvider
  tooltip={{ trigger: ['hover', 'focus'] }}
  popover={{ trigger: ['hover', 'focus'] }}
  popconfirm={{ trigger: ['hover', 'focus'] }}
>
  <App />
</ConfigProvider>
```



## Shared native props {#jguang-common-props}


> Tips: The following generic properties apply to most antd components; those not supported are described separately.

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| style | The additional style | CSSProperties | - |
| className | The additional css class | string | - |
| rootClassName | ClassName on the root element | string | - |
| autoFocus | Auto focus when component mounted, only effective for focusable elements like forms, links, etc. | boolean | false |


## Install and reproduce an example

```bash
npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23
```

Use ConfigProvider and native App; configure dayjs locale separately. Each example lists its complete source files and additional pinned dependencies in View code. Example names select demos, not universal component props. See the resource setup guide for theme, locale and SSR.

## Native type references

The source viewer includes unchanged native implementations and the following source declarations. Inherited types remain in their native packages. English source comments are preserved as code reference.

- `vendor/components/tooltip/PurePanel.tsx`
- `vendor/components/tooltip/hook/useMergedArrow.ts`
- `vendor/components/tooltip/index.tsx`
- `vendor/components/tooltip/style/index.ts`

## Source and license

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

Original bilingual prose and executable examples are retained. Website-only embeds and token tables are expanded locally. Ant Design is MIT; separately listed dependency notices also apply. Upload previews block outbound requests and do not provide a backend.

---

Index of all JGuang resources: https://jiguang132.com/llms.txt