Mastering Ant Design Popups: Fix Overlay Issues with getPopupContainer

Why the bug occurs

When Ant Design components such as Select, Dropdown, or Tooltip render their popup layers, they are by default mounted to document.body. Because the popup is outside the component’s DOM hierarchy, it inherits styles from the body and is affected by parent container properties like overflow: hidden or position: relative, leading to hidden, mis‑aligned, or non‑scrolling popups.

Understanding getPopupContainer

The getPopupContainer prop accepts a function that receives the trigger node ( triggerNode: HTMLElement) and returns the DOM element where the popup should be rendered. By returning a node that is a sibling or parent of the trigger, the popup stays within the same stacking context and follows the container’s scrolling and positioning.

getPopupContainer?: (triggerNode: HTMLElement) => HTMLElement;

Best practice

In a scrollable area, simply add the prop to direct the popup to the trigger’s parent node:

<Select
  defaultValue="FunTester"
  style={{ width: 120 }}
  getPopupContainer={trigger => trigger.parentNode}
>
  <Option value="jack">Jack</Option>
  <Option value="lucy">Lucy</Option>
  <Option value="FunTester">FunTester</Option>
</Select>

This ensures the dropdown moves together with its container during scrolling and avoids clipping or offset issues.

Common scenarios

Dropdown inside a scrollable container – use getPopupContainer={trigger => trigger.parentNode} to keep the menu inside the scroll area.

Tooltip inside a modal – the same prop prevents the tooltip from being hidden by the modal backdrop.

Unified popup management – return a dedicated DOM node, e.g., document.getElementById('popup-root'), to centralize all floating layers.

Special positioning (fixed elements) – return the appropriate container to avoid offset problems.

Lessons learned

If no scrolling, clipping, or special positioning issues are present, the default body mounting is fine.

When such issues appear, set getPopupContainer={trigger => trigger.parentNode} so the popup follows its parent.

For large projects, encapsulate a standard getPopupContainer implementation to maintain consistency across the codebase.

Conclusion

Popup misplacement is usually not a CSS or z‑index problem but the result of rendering to document.body. By correctly using getPopupContainer, developers can precisely control where popups are inserted, ensuring dropdowns, menus, and tooltips stay aligned, scroll with their containers, and provide a smoother user experience.