Ant Design Modal focus restoration lacks a stable configuration contract

Answer (first)

Ant Design v4 does not expose any prop that guarantees focus returns to the element that opened the Modal. In v5 a focusTriggerAfterClose prop exists, but it is not documented as a stable, public contract and may change in future releases. Therefore, for a version‑stable guarantee you must either rely on this prop in v5 (with caution) or implement explicit focus restoration in afterClose or onCancel callbacks.

Background and boundaries

The Modal component is a thin wrapper around rc‑dialog. rc‑dialog has an internal flag focusTriggerAfterClose that, when true, attempts to focus the element that triggered the dialog when the dialog’s afterClose lifecycle fires. In v4 the flag is always true by default, but the API surface does not expose it, so developers cannot guarantee its behaviour across releases. In v5 the flag can be set via the focusTriggerAfterClose prop, but the Ant Design docs do not list it as a stable contract; it is effectively an implementation detail.

When a modal is nested inside another modal, or when the modal’s portal container is moved outside the normal DOM hierarchy (for example, getContainer={false} or a custom getContainer function), the natural focus order can be disrupted. In these scenarios the internal focusTriggerAfterClose logic may not restore focus correctly because the original trigger element may no longer be in the same focusable context. The only reliable way to guarantee focus return in such layouts is to capture the trigger element before opening the modal and restore focus manually in the afterClose callback.

Practical steps for a team

1. Capture the trigger element. Before rendering the Modal, store a reference to the element that will open it.

   const triggerRef = useRef(null);
   const openModal = () => {
     triggerRef.current = document.activeElement;
     setVisible(true);
   };
   

2. Render the modal with the appropriate prop.
   • For Ant Design v5: <Modal focusTriggerAfterClose={true} ...> (default is true, but set explicitly for clarity).
   • For Ant Design v4: rely on default behaviour, but be aware it is undocumented.
3. Restore focus in afterClose. If you already have custom logic in afterClose that changes application state, add an explicit focus call after that logic.

   const handleAfterClose = () => {
     // your custom state updates
     // ...
     // restore focus
     if (triggerRef.current) {
       triggerRef.current.focus();
     }
   };
   

4. Handle nested and portal scenarios. When opening a nested modal, repeat the capture/restore pattern for each level. If you use a custom portal container, ensure the container is focusable and that the trigger element remains in the same focus context after the modal is closed.

Verification checklist

• Open the modal via Enter, Space, or a mouse click.
• Close the modal using Esc, a mask click, or a button inside the modal.
• After afterClose fires, check that document.activeElement equals the stored trigger element.
• Repeat the sequence for a nested modal and for a modal rendered in a custom portal.
• Run an accessibility audit (e.g., axe-core, Lighthouse) and confirm that focus is returned to the trigger element in all cases.

When to ask for more information

If your application uses a custom getContainer function or a non‑standard portal hierarchy, let us know the exact structure so we can provide a more targeted focus‑restoration strategy.