feat: Customise tooltip offset optional prop (#8988)

paulinashakirova · web-flow · commit 6ad3db7039f4 · 2025-09-05T13:53:07.000+02:00
diff --git a/packages/eui/changelogs/upcoming/8988.md b/packages/eui/changelogs/upcoming/8988.md
@@ -0,0 +1 @@
+- Added an optional `offset` prop to `EuiToolTip` to allow customizing the distance (in pixels) between the tooltip and its anchor.
diff --git a/packages/eui/src/components/tool_tip/__snapshots__/tool_tip.test.tsx.snap b/packages/eui/src/components/tool_tip/__snapshots__/tool_tip.test.tsx.snap
@@ -90,3 +90,45 @@ exports[`EuiToolTip shows tooltip on mouseover and focus 1`] = `
   </div>
 </body>
 `;
+
+exports[`EuiToolTip uses custom offset prop value 1`] = `
+<body
+  class="euiBody-hasPortalContent"
+>
+  <div>
+    <span
+      class="euiToolTipAnchor emotion-euiToolTipAnchor-inlineBlock"
+    >
+      <button
+        aria-describedby="generated-id"
+        data-test-subj="trigger"
+      >
+        Trigger
+      </button>
+    </span>
+  </div>
+  <div
+    data-euiportal="true"
+  >
+    <div
+      aria-label="aria-label"
+      class="euiToolTipPopover euiToolTip testClass1 testClass2 emotion-euiToolTip-top-euiTestCss"
+      data-position="top"
+      data-test-subj="test subject string"
+      id="generated-id"
+      offset="32"
+      position="top"
+      role="tooltip"
+      style="top: -32px; left: -10px;"
+    >
+      <div
+        class="euiToolTip__arrow emotion-euiToolTip__arrow-top"
+        style="left: 3px; top: 100%;"
+      />
+      <div>
+        content
+      </div>
+    </div>
+  </div>
+</body>
+`;
diff --git a/packages/eui/src/components/tool_tip/tool_tip.stories.tsx b/packages/eui/src/components/tool_tip/tool_tip.stories.tsx
@@ -14,7 +14,11 @@ import { LOKI_SELECTORS, lokiPlayDecorator } from '../../../.storybook/loki';
 import { sleep } from '../../test';
 import { EuiFlexGroup } from '../flex';
 import { EuiButton } from '../button';
-import { EuiToolTip, EuiToolTipProps } from './tool_tip';
+import {
+  EuiToolTip,
+  EuiToolTipProps,
+  DEFAULT_TOOLTIP_OFFSET,
+} from './tool_tip';
 
 const meta: Meta<EuiToolTipProps> = {
   title: 'Display/EuiToolTip',
@@ -47,6 +51,7 @@ const meta: Meta<EuiToolTipProps> = {
     repositionOnScroll: false,
     title: '',
     disableScreenReaderOutput: false,
+    offset: DEFAULT_TOOLTIP_OFFSET,
   },
 };
 enableFunctionToggleControls(meta, ['onMouseOut']);
diff --git a/packages/eui/src/components/tool_tip/tool_tip.test.tsx b/packages/eui/src/components/tool_tip/tool_tip.test.tsx
@@ -8,6 +8,7 @@
 
 import React, { useRef } from 'react';
 import { fireEvent } from '@testing-library/react';
+import { userEvent } from '@storybook/test';
 import {
   render,
   waitForEuiToolTipVisible,
@@ -61,6 +62,20 @@ describe('EuiToolTip', () => {
     await waitForEuiToolTipVisible();
   });
 
+  it('uses custom offset prop value', async () => {
+    const offsetValue = 32;
+    const { baseElement, getByRole } = render(
+      <EuiToolTip content="content" offset={offsetValue} {...requiredProps}>
+        <button data-test-subj="trigger">Trigger</button>
+      </EuiToolTip>
+    );
+    const trigger = getByRole('button');
+
+    await userEvent.hover(trigger);
+    await waitForEuiToolTipVisible();
+    expect(baseElement).toMatchSnapshot();
+  });
+
   test('anchor props are rendered', () => {
     const { baseElement } = render(
       <EuiToolTip
diff --git a/packages/eui/src/components/tool_tip/tool_tip.tsx b/packages/eui/src/components/tool_tip/tool_tip.tsx
@@ -31,6 +31,7 @@ export const POSITIONS = ['top', 'right', 'bottom', 'left'] as const;
 const DISPLAYS = ['inlineBlock', 'block'] as const;
 
 export type ToolTipDelay = 'regular' | 'long';
+export const DEFAULT_TOOLTIP_OFFSET = 16;
 
 const delayToMsMap: { [key in ToolTipDelay]: number } = {
   regular: 250,
@@ -121,6 +122,11 @@ export interface EuiToolTipProps extends CommonProps {
    * hidden.
    */
   onMouseOut?: (event: ReactMouseEvent<HTMLSpanElement, MouseEvent>) => void;
+
+  /**
+   * Offset in pixels from the anchor. Defaults to 16.
+   */
+  offset?: number;
 }
 
 interface State {
@@ -220,6 +226,7 @@ export class EuiToolTip extends Component<EuiToolTipProps, State> {
 
   positionToolTip = () => {
     const requestedPosition = this.props.position;
+    const offset = this.props.offset ?? DEFAULT_TOOLTIP_OFFSET;
 
     if (!this.anchor || !this.popover) {
       return;
@@ -229,7 +236,7 @@ export class EuiToolTip extends Component<EuiToolTipProps, State> {
       anchor: this.anchor,
       popover: this.popover,
       position: requestedPosition,
-      offset: 16, // offset popover 16px from the anchor
+      offset,
       arrowConfig: {
         arrowWidth: 12,
         arrowBuffer: 4,
diff --git a/packages/website/docs/components/display/tooltip.mdx b/packages/website/docs/components/display/tooltip.mdx
@@ -14,6 +14,7 @@ Generally, tooltips should provide short, **non-essential**, contextual informat
 :::
 
 Wrap **EuiToolTip** around any item that you need a tooltip for and provide the `content` and optionally the `title`. The `position` prop will take a suggested position, but will change it if the tooltip gets too close to the edge of the screen.
+You can adjust the distance between the tooltip and its anchor using the `offset` prop. By default, this value is `16`.
 
 ```tsx interactive
 import React from 'react';
@@ -65,6 +66,12 @@ export default () => (
           <EuiIcon tabIndex="0" type="warning" title="Icon with tooltip" />
         </EuiToolTip>
       </p>
+      <p>
+        This tooltip has a{' '}
+        <EuiToolTip position="right" content="Here is some tooltip text" offset={32}>
+          <EuiLink href="#">custom offset</EuiLink>
+        </EuiToolTip>
+      </p>
     </EuiText>
   </div>
 );

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+- Added an optional `offset` prop to `EuiToolTip` to allow customizing the distance (in pixels) between the tooltip and its anchor.