Tooltip

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

Common API

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

ConfigProvider - 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.

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 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.

Declaration source: vendor/components/tooltip/style/index.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?

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?

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

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

If need update content when close, you can set fresh property (#44830):

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

Why doesn't Tooltip realign after a layout change?

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). 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, #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.

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:

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.

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

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

Install and reproduce an example

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.