Admin Modal Management#

Overview#

The Strapi admin panel's relation modal allows editors to open, edit, and create related documents inline without leaving the parent edit view. It is the primary source of several cross-cutting modal-management concerns in the Content Manager: viewport containment, scroll affordance, unsaved-changes state persistence, and parent-document refetch side effects triggered on modal close.

All modal state and navigation logic lives in RelationModal.tsx. Supporting files include DocumentActions.tsx (relation-to-parent connection logic) and useDocumentLayout.ts (schema resolution guards).

Modal Architecture#

Renderer Hierarchy#

RelationModal.tsx uses a three-tier renderer pattern 1:

• RelationModalRenderer — checks at render time whether a parent RelationModal context exists.
• RootRelationRenderer — no existing context: creates a useReducer, mounts RelationModalProvider. 2
• NestedRelationRenderer — context exists: reads dispatch from parent, creates no new reducer. 3

The active document is always state.documentHistory.at(-1) ?? rootDocumentMeta, so deeper navigation simply pushes onto the stack. 4

State Shape#

The State interface tracks:

Seven action types handle navigation: GO_TO_RELATION, GO_BACK, GO_FULL_PAGE, GO_TO_CREATED_RELATION, CANCEL_CONFIRM_DIALOG, CLOSE_MODAL, SET_HAS_UNSAVED_CHANGES. When hasUnsavedChanges is true, any navigation action sets confirmDialogIntent instead of executing, triggering a discard-changes dialog.

Component Context Isolation#

The modal shell resets the ComponentProvider context (id=undefined, level=-1, uid=undefined) to prevent inheriting the parent form's componentUID and level. Without this, relation search queries would resolve to the wrong model and ID 4.

Refetch Side Effect on Modal Close#

When the modal closes without unsaved changes, handleCloseModal calls:

triggerRefetchDocument(rootDocumentMeta, /* preferCache= */ true)

This re-fetches the root (parent) document via useLazyGetDocumentQuery to refresh relation counts and field values that may have changed inside the modal. The preferCache: true flag serves RTK Query cache when valid. An inline TODO comment flags this as a workaround — ideally invalidatesTags would handle the refetch automatically 5.

This refetch has two known downstream side effects:

1. Pagination reset — The RelationsField component loses its local currentPage state on refetch, reverting to 5 entries and making "Load More" non-functional 6.
2. DynamicZone crash — SET_INITIAL_VALUES resets form state with the refetched payload, which may contain null for empty DZ fields. DynamicZone/Field.tsx uses a default parameter = [] that only fires for undefined, so accessing .length on null throws TypeError 7.

Known Issues#

Parent Form State Discarded on Relation Creation — PR #27081#

Bug: Creating a relation on the fly (especially from inside a newly added dynamic-zone component) silently discards unsaved edits on the parent form 8.

Root cause: connectRelationToParent sourced parentDataToUpdate from getInitialFormValues() — the server-fetched initial state — rather than the current in-memory form values. Fields filled in after the last save were lost 9.

Fix (PR #27081): Modal State now carries a getParentFormValues closure captured at modal-open time 10. connectRelationToParent merges into existing connect entries (deduped by documentId + locale) instead of overwriting, preserving any pending relations in the same field 8.

DynamicZone Crash After Closing Relation Modal — Issue #26813#

Bug: React crashes with TypeError: Cannot read properties of null (reading 'length') at DynamicZone/Field.tsx after closing any relation modal on a content type that also has a DynamicZone 7.

Root cause (chain): Modal close triggers triggerRefetchDocument → SET_INITIAL_VALUES resets form state with the refetched payload → the payload contains null for empty DZ fields → DynamicZone/Field.tsx uses a default parameter = [] that only fires for undefined, not null, causing .length to throw 7.

Suggested fixes: Nullish coalescing in DynamicZone/Field.tsx (_rawDZValue ?? []), or fixing traverseData to not short-circuit for null before calling the predicate 7.

On-the-Fly Relation Creation Crash in DZ Component — Issue #27246#

Bug: Creating a new related entry from a relation field inside a component nested in a dynamic zone throws immediately on modal open: "this is likely a bug with Strapi" 11.

Status: Under investigation; root cause not yet documented. Selecting an existing relation works without error.

Relation Field Resets to 5 Entries After Modal Close — Issue #27199#

Bug: After loading more than 5 entries and opening a relation modal, closing the modal resets the relation field to 5 entries and "Load More" stops working 6.

Root cause: triggerRefetchDocument on modal close causes RelationsField to lose its local currentPage state, resetting to page 1. The RTK Query cache merge then replaces all accumulated entries with first-page results only.

Pattern note: Issues #26813 and #27199 share a common root: the triggerRefetchDocument call on every clean modal close is a systemic source of state loss. The long-term fix is replacing it with RTK Query invalidatesTags.

Scroll and Layout Issues#

Duplicate Scrollbar in List View (Chromium) — PR #26133#

Bug: Large collection types produced a double scrollbar in Chromium, allowing users to scroll past the content 12.

Root cause: Absolutely-positioned descendants of OverflowingItem resolved their containing block to <html> (since all ancestors were position: static), inflating html.scrollHeight and surfacing a window-level scrollbar. Firefox computes scrollHeight differently and was unaffected 12.

Fix: OverflowingItem in Layout.tsx received position: relative and overflow-x: hidden, anchoring absolute descendants inside its clipping region.

Sidenav Scroll Bleeds into Main Content — PR #25379#

Bug: Scrolling inside the side navigation simultaneously scrolled the main content area 13.

Root cause: Sticky positioning caused scroll chaining between the sidenav and the main content.

Fix: MainSubNav in SubNav.tsx received overscroll-behavior: contain inside the medium breakpoint, isolating scroll to the hovered container.

Locale Picker Hides Entries Without Scroll Indicator — Issue #26562#

Bug: When 5+ locales are configured, the locale picker dropdown silently hides locales beyond the 4th. No scroll indicator is visible in most OS/browser themes 14.

Root cause: The SingleSelect component from @strapi/design-system applies max-height: 15.6rem (fits ~4 items) with no SelectScrollUpButton / SelectScrollDownButton from Radix UI. The fix is in the design system layer.

Key Files#