Ant Design Modal Z-Index Conflicts: Diagnostic Guide for Stacking Context Issues

The Problem: Hidden Overlays in Ant Design

You open an Ant Design Modal or Drawer, but it appears behind page elements, is clipped by a container, or fails to cover the screen. This happens not because the z-index is too low, but because the component is trapped inside a CSS Stacking Context.

A stacking context is a three-dimensional layer formed by HTML elements. When a parent has certain CSS properties, it creates a local coordinate system for z-index. Any child—even one with z-index: 9999—cannot appear above an element outside that parent if the parent itself is layered lower.

Diagnostic Matrix: Identifying the Cause

Symptom	Likely Cause	Diagnostic Check
Modal visible but behind header/sidebar	Global Z-Index Collision	Check third-party widgets (e.g., chatbots) for z-indices > 1000
Modal clipped by parent container	Local Stacking Context	Look for transform, filter, or perspective on ancestors
Modal appears but mask is behind content	DOM Nesting Issue	Verify .ant-modal-mask is not inside a positioned div

Step-by-Step Resolution Path

Follow these checks in order. Do not apply CSS overrides until the DOM structure is verified.

1. Check for Stacking Context Triggers

Inspect parent elements of your Modal or Drawer in DevTools. Look for these CSS properties on any ancestor:

• transform (e.g., translate, scale)
• filter (e.g., blur, drop-shadow)
• opacity (values less than 1)
• perspective
• will-change

If any are present, the Modal is trapped. The most effective fix is to "teleport" the component to the document root.

2. Implement the getContainer Prop

Ant Design provides the getContainer prop to move rendered HTML outside the current DOM hierarchy. By default, most overlays append to document.body, but custom configurations may nest them.

import { Modal } from 'antd';

<Modal
  title="Layering Fix"
  open={isVisible}
  getContainer={() => document.body}
>
  <p>This content will now ignore parent stacking contexts.</p>
</Modal>

Risk: If your Modal relies on CSS variables from a parent (e.g., .theme-dark { --primary-color: #000; }), moving to document.body disconnects those variables. Move variables to :root or body level.

3. Adjust Global Z-Index via ConfigProvider

If the Modal is at body level but still hidden by third-party libraries (Google Maps, chat widgets), raise the base z-index for all Ant Design components.

import { ConfigProvider } from 'antd';

<ConfigProvider>
  <App />
</ConfigProvider>

For version-agnostic shifts, target Ant Design overlay classes in global CSS, but avoid !important as it breaks internal managers.

Verification and Testing

1. DOM Inspection: Open DevTools (F12). Trigger Modal. Ensure .ant-modal-wrap is a direct child of <body>.
2. Computed Value Check: Select .ant-modal-mask. Verify z-index is 1000+.
3. Interaction Test: Ensure mask click closes modal and focus trap works.

When to Escalate

If issues persist despite correct fixes, the problem may involve:

• A global CSS reset overriding Ant Design's defaults
• A third-party framework (Tailwind, Bootstrap) conflicting
• Version incompatibility with getContainer