feat: add portalElementRef prop to support custom portal elements (#1064)

citizensas · Sassoun Derderian · web-flow · commit ea0ff475eb3e · 2025-07-10T20:26:11.000+02:00
Co-authored-by: Sassoun Derderian &lt;sassound@adobe.com&gt;
diff --git a/packages/cells/src/cells/dropdown-cell.tsx b/packages/cells/src/cells/dropdown-cell.tsx
@@ -62,7 +62,7 @@ const ReadOnlyWrap = styled.div`
 `;
 
 const Editor: ReturnType<ProvideEditorCallback<DropdownCell>> = p => {
-    const { value: cell, onFinishedEditing, initialValue } = p;
+    const { value: cell, onFinishedEditing, initialValue, portalElementRef } = p;
     const { allowedValues, value: valueIn } = cell.data;
 
     const [value, setValue] = React.useState(valueIn);
@@ -151,7 +151,7 @@ const Editor: ReturnType<ProvideEditorCallback<DropdownCell>> = p => {
                         },
                     };
                 }}
-                menuPortalTarget={document.getElementById("portal")}
+                menuPortalTarget={portalElementRef?.current ??  document.getElementById("portal")}
                 autoFocus={true}
                 openMenuOnFocus={true}
                 components={{
diff --git a/packages/cells/src/cells/multi-select-cell.tsx b/packages/cells/src/cells/multi-select-cell.tsx
@@ -131,7 +131,7 @@ const CustomMenu: React.FC<CustomMenuProps> = p => {
 export type MultiSelectCell = CustomCell<MultiSelectCellProps>;
 
 const Editor: ReturnType<ProvideEditorCallback<MultiSelectCell>> = p => {
-    const { value: cell, initialValue, onChange, onFinishedEditing } = p;
+    const { value: cell, initialValue, onChange, onFinishedEditing, portalElementRef } = p;
     const { options: optionsIn, values: valuesIn, allowCreation, allowDuplicates } = cell.data;
 
     const theme = useTheme();
@@ -343,7 +343,7 @@ const Editor: ReturnType<ProvideEditorCallback<MultiSelectCell>> = p => {
                 value={resolveValues(value, options, allowDuplicates)}
                 onKeyDown={cell.readonly ? undefined : handleKeyDown}
                 menuPlacement={"auto"}
-                menuPortalTarget={document.getElementById("portal")}
+                menuPortalTarget={portalElementRef?.current ??  document.getElementById("portal")}
                 autoFocus={true}
                 openMenuOnFocus={true}
                 openMenuOnClick={true}
diff --git a/packages/core/API.md b/packages/core/API.md
@@ -2,12 +2,27 @@
 
 ## HTML/CSS Prerequisites
 
-Currently the Grid depends on there being a root level "portal" div in your HTML. Insert this snippet as the last child of your `<body>` tag:
+The Grid depends on there being a root level "portal" div in your HTML. Insert this snippet as the last child of your `<body>` tag:
 
 ```HTML
 <div id="portal" style="position: fixed; left: 0; top: 0; z-index: 9999;" />
 ```
 
+or you can create a portal element yourself using the `createPortal` function from `react-dom` and pass it to the DataEditor via the `portalElementRef` prop.
+
+```jsx
+const portalRef = useRef(null);
+<>
+  {
+    createPortal(
+      <div ref={portalRef} style="position: fixed; left: 0; top: 0; z-index: 9999;" />, 
+      document.body
+    )
+  }
+  <DataEditor width={500} height={300} portalElementRef={portalRef} {...props} />
+</>
+```
+
 Once you've got that done, the easiest way to use the Data Grid is to give it a fixed size:
 
 ```jsx
@@ -71,14 +86,15 @@ All data grids must set these props. These props are the bare minimum required t
 Most data grids will want to set the majority of these props one way or another.
 
 | Name                                              | Description                                                                                                                                                                                                                                                         |
-| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+|---------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | [fixedShadowX](#fixedshadow)                      | Enable/disable a shadow behind fixed columns on the X axis.                                                                                                                                                                                                         |
 | [fixedShadowY](#fixedshadow)                      | Enable/disable a shadow behind the header(s) on the Y axis.                                                                                                                                                                                                         |
 | [freezeColumns](#freezecolumns)                   | The number of columns which should remain in place when scrolling horizontally. The row marker column, if enabled is always frozen and is not included in this count.                                                                                               |
 | [getCellsForSelection](#getcellsforselection)     | Used to fetch large amounts of cells at once. Used for copy/paste, if unset copy will not work.                                                                                                                                                                     |
 | [markdownDivCreateNode](#markdowndivcreatenode)   | If specified, it will be used to render Markdown, instead of the default Markdown renderer used by the Grid. You'll want to use this if you need to process your Markdown for security purposes, or if you want to use a renderer with different Markdown features. |
 | [onVisibleRegionChanged](#onvisibleregionchanged) | Emits whenever the visible rows/columns changes.                                                                                                                                                                                                                    |
 | [provideEditor](#provideeditor)                   | Callback for providing a custom editor for a cell.                                                                                                                                                                                                                  |
+| [portalElementRef](#portalelementref)             | A ref to the portal element to use for the overlay editor.                                                                                                                                                                                                          |
 | [rowHeight](#rowheight)                           | Callback or number used to specify the height of a given row.                                                                                                                                                                                                       |
 | [rowMarkers](#rowmarkers)                         | Enable/disable row marker column on the left. Can show row numbers, selection boxes, or both.                                                                                                                                                                       |
 | [smoothScrollX](#smoothscroll)                    | Enable/disable smooth scrolling on the X axis.                                                                                                                                                                                                                      |
@@ -610,6 +626,12 @@ When provided the `provideEditor` callbacks job is to be a constructor for funct
 
 ---
 
+## portalElementRef
+
+Defaults to div#portal
+
+---
+
 ## rowHeight
 
 ```ts
diff --git a/packages/core/src/data-editor/data-editor.tsx b/packages/core/src/data-editor/data-editor.tsx
@@ -677,6 +677,11 @@ export interface DataEditorProps extends Props, Pick<DataGridSearchProps, "image
     readonly scrollToActiveCell?: boolean;
 
     readonly drawFocusRing?: boolean | "no-editor";
+
+    /**
+     * Allows overriding the default portal element.
+     */
+    readonly portalElementRef?: React.RefObject<HTMLElement>;
 }
 
 type ScrollToFn = (
@@ -875,6 +880,7 @@ const DataEditorImpl: React.ForwardRefRenderFunction<DataEditorRef, DataEditorPr
         resizeIndicator,
         scrollToActiveCell = true,
         drawFocusRing: drawFocusRingIn = true,
+        portalElementRef,
     } = p;
 
     const drawFocusRing = drawFocusRingIn === "no-editor" ? overlay === undefined : drawFocusRingIn;
@@ -4172,6 +4178,7 @@ const DataEditorImpl: React.ForwardRefRenderFunction<DataEditorRef, DataEditorPr
                             className={experimental?.isSubGrid === true ? "click-outside-ignore" : undefined}
                             provideEditor={provideEditor}
                             imageEditorOverride={imageEditorOverride}
+                            portalElementRef={portalElementRef}
                             onFinishEditing={onFinishEditing}
                             markdownDivCreateNode={markdownDivCreateNode}
                             isOutsideClick={isOutsideClick}
diff --git a/packages/core/src/internal/data-grid-overlay-editor/data-grid-overlay-editor.tsx b/packages/core/src/internal/data-grid-overlay-editor/data-grid-overlay-editor.tsx
@@ -34,6 +34,7 @@ interface DataGridOverlayEditorProps {
     readonly onFinishEditing: (newCell: GridCell | undefined, movement: readonly [-1 | 0 | 1, -1 | 0 | 1]) => void;
     readonly forceEditMode: boolean;
     readonly highlight: boolean;
+    readonly portalElementRef?: React.RefObject<HTMLElement>
     readonly imageEditorOverride?: ImageEditorType;
     readonly getCellRenderer: GetCellRendererCallback;
     readonly markdownDivCreateNode?: (content: string) => DocumentFragment;
@@ -62,6 +63,7 @@ const DataGridOverlayEditor: React.FunctionComponent<DataGridOverlayEditorProps>
         id,
         cell,
         bloom,
+        portalElementRef,
         validateCell,
         getCellRenderer,
         provideEditor,
@@ -177,6 +179,7 @@ const DataGridOverlayEditor: React.FunctionComponent<DataGridOverlayEditorProps>
         const CustomEditor = isObjectEditor ? editorProvider.editor : editorProvider;
         editor = (
             <CustomEditor
+                portalElementRef={portalElementRef}
                 isHighlighted={highlight}
                 onChange={setTempValue}
                 value={targetValue}
@@ -196,11 +199,11 @@ const DataGridOverlayEditor: React.FunctionComponent<DataGridOverlayEditorProps>
     styleOverride = { ...styleOverride, ...stayOnScreenStyle };
 
     // Consider imperatively creating and adding the element to the dom?
-    const portalElement = document.getElementById("portal");
+    const portalElement = portalElementRef?.current ?? document.getElementById("portal");
     if (portalElement === null) {
         // eslint-disable-next-line no-console
         console.error(
-            'Cannot open Data Grid overlay editor, because portal not found.  Please add `<div id="portal" />` as the last child of your `<body>`.'
+            'Cannot open Data Grid overlay editor, because portal not found. Please, either provide a portalElementRef or add `<div id="portal" />` as the last child of your `<body>`.'
         );
         return null;
     }
diff --git a/packages/core/src/internal/data-grid/data-grid-types.ts b/packages/core/src/internal/data-grid/data-grid-types.ts
@@ -395,6 +395,7 @@ export type ProvideEditorComponent<T extends InnerGridCell> = React.FunctionComp
     readonly forceEditMode: boolean;
     readonly isValid?: boolean;
     readonly theme: Theme;
+    readonly portalElementRef?: React.RefObject<HTMLElement>;
 }>;
 
 type ObjectEditorCallbackResult<T extends InnerGridCell> = {
