Skip to content

[portals] Create portal elements inside React #2889

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: master
Choose a base branch
from
Open

[portals] Create portal elements inside React #2889

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
5de02b5
[portals] Ensure container is reactive from undefined
atomiks Sep 26, 2025
4e6bfde
[portals] Create portal element inside React
atomiks Oct 2, 2025
1c16f65
docs:api
atomiks Oct 2, 2025
3da63bf
Fix DemoLoader
atomiks Oct 3, 2025
5d77d0f
lint
atomiks Oct 3, 2025
5fee158
Merge branch 'master' into feat/portal-elements
atomiks Oct 7, 2025
1183e7a
lint
atomiks Oct 7, 2025
e3b5012
lint
atomiks Oct 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 10 additions & 4 deletions docs/reference/generated/alert-dialog-portal.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,27 @@
{
"name": "AlertDialogPortal",
"description": "A portal element that moves the popup to a different part of the DOM.\nBy default, the portal element is appended to `<body>`.",
"description": "A portal element that moves the popup to a different part of the DOM.\nBy default, the portal element is appended to `<body>`.\nRenders a `<div>` element.",
"props": {
"container": {
"type": "HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null",
"description": "A parent element to render the portal element into.",
"detailedType": "| HTMLElement\n| ShadowRoot\n| React.RefObject<HTMLElement | ShadowRoot | null>\n| null\n| undefined"
},
"children": {
"type": "ReactNode",
"detailedType": "React.ReactNode"
"className": {
"type": "string | ((state: AlertDialog.Portal.State) => string)",
"description": "CSS class applied to the element, or a function that\nreturns a class based on the component’s state.",
"detailedType": "| string\n| ((state: AlertDialog.Portal.State) => string)"
},
"keepMounted": {
"type": "boolean",
"default": "false",
"description": "Whether to keep the portal mounted in the DOM while the popup is hidden.",
"detailedType": "boolean | undefined"
},
"render": {
"type": "ReactElement | ((props: HTMLProps, state: AlertDialog.Portal.State) => ReactElement)",
"description": "Allows you to replace the component’s HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render.",
"detailedType": "| ReactElement\n| ((\n props: HTMLProps,\n state: AlertDialog.Portal.State,\n ) => ReactElement)"
}
},
"dataAttributes": {},
Expand Down
17 changes: 11 additions & 6 deletions docs/reference/generated/combobox-portal.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,26 @@
{
"name": "ComboboxPortal",
"description": "A portal element that moves the popup to a different part of the DOM.\nBy default, the portal element is appended to `<body>`.",
"description": "A portal element that moves the popup to a different part of the DOM.\nBy default, the portal element is appended to `<body>`.\nRenders a `<div>` element.",
"props": {
"container": {
"type": "HTMLElement | RefObject<HTMLElement | null> | null",
"type": "HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null",
"description": "A parent element to render the portal element into.",
"detailedType": "| HTMLElement\n| React.RefObject<HTMLElement | null>\n| null\n| undefined"
"detailedType": "| HTMLElement\n| ShadowRoot\n| React.RefObject<HTMLElement | ShadowRoot | null>\n| null\n| undefined"
},
"children": {
"type": "ReactNode",
"detailedType": "React.ReactNode"
"className": {
"type": "string | ((state: Combobox.Portal.State) => string)",
"description": "CSS class applied to the element, or a function that\nreturns a class based on the component’s state."
},
"keepMounted": {
"type": "boolean",
"default": "false",
"description": "Whether to keep the portal mounted in the DOM while the popup is hidden.",
"detailedType": "boolean | undefined"
},
"render": {
"type": "ReactElement | ((props: HTMLProps, state: Combobox.Portal.State) => ReactElement)",
"description": "Allows you to replace the component’s HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render.",
"detailedType": "| ReactElement\n| ((\n props: HTMLProps,\n state: Combobox.Portal.State,\n ) => ReactElement)"
}
},
"dataAttributes": {},
Expand Down
13 changes: 9 additions & 4 deletions docs/reference/generated/dialog-portal.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,26 @@
{
"name": "DialogPortal",
"description": "A portal element that moves the popup to a different part of the DOM.\nBy default, the portal element is appended to `<body>`.",
"description": "A portal element that moves the popup to a different part of the DOM.\nBy default, the portal element is appended to `<body>`.\nRenders a `<div>` element.",
"props": {
"container": {
"type": "HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null",
"description": "A parent element to render the portal element into.",
"detailedType": "| HTMLElement\n| ShadowRoot\n| React.RefObject<HTMLElement | ShadowRoot | null>\n| null\n| undefined"
},
"children": {
"type": "ReactNode",
"detailedType": "React.ReactNode"
"className": {
"type": "string | ((state: Dialog.Portal.State) => string)",
"description": "CSS class applied to the element, or a function that\nreturns a class based on the component’s state."
},
"keepMounted": {
"type": "boolean",
"default": "false",
"description": "Whether to keep the portal mounted in the DOM while the popup is hidden.",
"detailedType": "boolean | undefined"
},
"render": {
"type": "ReactElement | ((props: HTMLProps, state: Dialog.Portal.State) => ReactElement)",
"description": "Allows you to replace the component’s HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render.",
"detailedType": "| ReactElement\n| ((\n props: HTMLProps,\n state: Dialog.Portal.State,\n ) => ReactElement)"
}
},
"dataAttributes": {},
Expand Down
13 changes: 9 additions & 4 deletions docs/reference/generated/menu-portal.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,26 @@
{
"name": "MenuPortal",
"description": "A portal element that moves the popup to a different part of the DOM.\nBy default, the portal element is appended to `<body>`.",
"description": "A portal element that moves the popup to a different part of the DOM.\nBy default, the portal element is appended to `<body>`.\nRenders a `<div>` element.",
"props": {
"container": {
"type": "HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null",
"description": "A parent element to render the portal element into.",
"detailedType": "| HTMLElement\n| ShadowRoot\n| React.RefObject<HTMLElement | ShadowRoot | null>\n| null\n| undefined"
},
"children": {
"type": "ReactNode",
"detailedType": "React.ReactNode"
"className": {
"type": "string | ((state: Menu.Portal.State) => string)",
"description": "CSS class applied to the element, or a function that\nreturns a class based on the component’s state."
},
"keepMounted": {
"type": "boolean",
"default": "false",
"description": "Whether to keep the portal mounted in the DOM while the popup is hidden.",
"detailedType": "boolean | undefined"
},
"render": {
"type": "ReactElement | ((props: HTMLProps, state: Menu.Portal.State) => ReactElement)",
"description": "Allows you to replace the component’s HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render.",
"detailedType": "| ReactElement\n| ((\n props: HTMLProps,\n state: Menu.Portal.State,\n ) => ReactElement)"
}
},
"dataAttributes": {},
Expand Down
18 changes: 12 additions & 6 deletions docs/reference/generated/navigation-menu-portal.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,27 @@
{
"name": "NavigationMenuPortal",
"description": "A portal element that moves the popup to a different part of the DOM.\nBy default, the portal element is appended to `<body>`.",
"description": "A portal element that moves the popup to a different part of the DOM.\nBy default, the portal element is appended to `<body>`.\nRenders a `<div>` element.",
"props": {
"container": {
"type": "HTMLElement | RefObject<HTMLElement | null> | null",
"type": "HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null",
"description": "A parent element to render the portal element into.",
"detailedType": "| HTMLElement\n| React.RefObject<HTMLElement | null>\n| null\n| undefined"
"detailedType": "| HTMLElement\n| ShadowRoot\n| React.RefObject<HTMLElement | ShadowRoot | null>\n| null\n| undefined"
},
"children": {
"type": "ReactNode",
"detailedType": "React.ReactNode"
"className": {
"type": "string | ((state: NavigationMenu.Portal.State) => string)",
"description": "CSS class applied to the element, or a function that\nreturns a class based on the component’s state.",
"detailedType": "| string\n| ((state: NavigationMenu.Portal.State) => string)"
},
"keepMounted": {
"type": "boolean",
"default": "false",
"description": "Whether to keep the portal mounted in the DOM while the popup is hidden.",
"detailedType": "boolean | undefined"
},
"render": {
"type": "ReactElement | ((props: HTMLProps, state: NavigationMenu.Portal.State) => ReactElement)",
"description": "Allows you to replace the component’s HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render.",
"detailedType": "| ReactElement\n| ((\n props: HTMLProps,\n state: NavigationMenu.Portal.State,\n ) => ReactElement)"
}
},
"dataAttributes": {},
Expand Down
13 changes: 9 additions & 4 deletions docs/reference/generated/popover-portal.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,26 @@
{
"name": "PopoverPortal",
"description": "A portal element that moves the popup to a different part of the DOM.\nBy default, the portal element is appended to `<body>`.",
"description": "A portal element that moves the popup to a different part of the DOM.\nBy default, the portal element is appended to `<body>`.\nRenders a `<div>` element.",
"props": {
"container": {
"type": "HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null",
"description": "A parent element to render the portal element into.",
"detailedType": "| HTMLElement\n| ShadowRoot\n| React.RefObject<HTMLElement | ShadowRoot | null>\n| null\n| undefined"
},
"children": {
"type": "ReactNode",
"detailedType": "React.ReactNode"
"className": {
"type": "string | ((state: Popover.Portal.State) => string)",
"description": "CSS class applied to the element, or a function that\nreturns a class based on the component’s state."
},
"keepMounted": {
"type": "boolean",
"default": "false",
"description": "Whether to keep the portal mounted in the DOM while the popup is hidden.",
"detailedType": "boolean | undefined"
},
"render": {
"type": "ReactElement | ((props: HTMLProps, state: Popover.Portal.State) => ReactElement)",
"description": "Allows you to replace the component’s HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render.",
"detailedType": "| ReactElement\n| ((\n props: HTMLProps,\n state: Popover.Portal.State,\n ) => ReactElement)"
}
},
"dataAttributes": {},
Expand Down
14 changes: 10 additions & 4 deletions docs/reference/generated/preview-card-portal.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,27 @@
{
"name": "PreviewCardPortal",
"description": "A portal element that moves the popup to a different part of the DOM.\nBy default, the portal element is appended to `<body>`.",
"description": "A portal element that moves the popup to a different part of the DOM.\nBy default, the portal element is appended to `<body>`.\nRenders a `<div>` element.",
"props": {
"container": {
"type": "HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null",
"description": "A parent element to render the portal element into.",
"detailedType": "| HTMLElement\n| ShadowRoot\n| React.RefObject<HTMLElement | ShadowRoot | null>\n| null\n| undefined"
},
"children": {
"type": "ReactNode",
"detailedType": "React.ReactNode"
"className": {
"type": "string | ((state: PreviewCard.Portal.State) => string)",
"description": "CSS class applied to the element, or a function that\nreturns a class based on the component’s state.",
"detailedType": "| string\n| ((state: PreviewCard.Portal.State) => string)"
},
"keepMounted": {
"type": "boolean",
"default": "false",
"description": "Whether to keep the portal mounted in the DOM while the popup is hidden.",
"detailedType": "boolean | undefined"
},
"render": {
"type": "ReactElement | ((props: HTMLProps, state: PreviewCard.Portal.State) => ReactElement)",
"description": "Allows you to replace the component’s HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render.",
"detailedType": "| ReactElement\n| ((\n props: HTMLProps,\n state: PreviewCard.Portal.State,\n ) => ReactElement)"
}
},
"dataAttributes": {},
Expand Down
13 changes: 9 additions & 4 deletions docs/reference/generated/select-portal.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,20 @@
{
"name": "SelectPortal",
"description": "A portal element that moves the popup to a different part of the DOM.\nBy default, the portal element is appended to `<body>`.",
"description": "A portal element that moves the popup to a different part of the DOM.\nBy default, the portal element is appended to `<body>`.\nRenders a `<div>` element.",
"props": {
"container": {
"type": "HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null",
"description": "A parent element to render the portal element into.",
"detailedType": "| HTMLElement\n| ShadowRoot\n| React.RefObject<HTMLElement | ShadowRoot | null>\n| null\n| undefined"
},
"children": {
"type": "ReactNode",
"detailedType": "React.ReactNode"
"className": {
"type": "string | ((state: Select.Portal.State) => string)",
"description": "CSS class applied to the element, or a function that\nreturns a class based on the component’s state."
},
"render": {
"type": "ReactElement | ((props: HTMLProps, state: Select.Portal.State) => ReactElement)",
"description": "Allows you to replace the component’s HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render.",
"detailedType": "| ReactElement\n| ((\n props: HTMLProps,\n state: Select.Portal.State,\n ) => ReactElement)"
}
},
"dataAttributes": {},
Expand Down
17 changes: 11 additions & 6 deletions docs/reference/generated/toast-portal.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,20 @@
{
"name": "ToastPortal",
"description": "A portal element that moves the viewport to a different part of the DOM.\nBy default, the portal element is appended to `<body>`.",
"description": "A portal element that moves the viewport to a different part of the DOM.\nBy default, the portal element is appended to `<body>`.\nRenders a `<div>` element.",
"props": {
"container": {
"type": "HTMLElement | RefObject<HTMLElement | null> | null",
"type": "HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null",
"description": "A parent element to render the portal element into.",
"detailedType": "| HTMLElement\n| React.RefObject<HTMLElement | null>\n| null\n| undefined"
"detailedType": "| HTMLElement\n| ShadowRoot\n| React.RefObject<HTMLElement | ShadowRoot | null>\n| null\n| undefined"
},
"children": {
"type": "ReactNode",
"detailedType": "React.ReactNode"
"className": {
"type": "string | ((state: any) => string)",
"description": "CSS class applied to the element, or a function that\nreturns a class based on the component’s state."
},
"render": {
"type": "ReactElement | ((props: HTMLProps, state: any) => ReactElement)",
"description": "Allows you to replace the component’s HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render.",
"detailedType": "| ReactElement\n| ((props: HTMLProps, state: any) => ReactElement)"
}
},
"dataAttributes": {},
Expand Down
13 changes: 9 additions & 4 deletions docs/reference/generated/tooltip-portal.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,26 @@
{
"name": "TooltipPortal",
"description": "A portal element that moves the popup to a different part of the DOM.\nBy default, the portal element is appended to `<body>`.",
"description": "A portal element that moves the popup to a different part of the DOM.\nBy default, the portal element is appended to `<body>`.\nRenders a `<div>` element.",
"props": {
"container": {
"type": "HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null",
"description": "A parent element to render the portal element into.",
"detailedType": "| HTMLElement\n| ShadowRoot\n| React.RefObject<HTMLElement | ShadowRoot | null>\n| null\n| undefined"
},
"children": {
"type": "ReactNode",
"detailedType": "React.ReactNode"
"className": {
"type": "string | ((state: Tooltip.Portal.State) => string)",
"description": "CSS class applied to the element, or a function that\nreturns a class based on the component’s state."
},
"keepMounted": {
"type": "boolean",
"default": "false",
"description": "Whether to keep the portal mounted in the DOM while the popup is hidden.",
"detailedType": "boolean | undefined"
},
"render": {
"type": "ReactElement | ((props: HTMLProps, state: Tooltip.Portal.State) => ReactElement)",
"description": "Allows you to replace the component’s HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render.",
"detailedType": "| ReactElement\n| ((\n props: HTMLProps,\n state: Tooltip.Portal.State,\n ) => ReactElement)"
}
},
"dataAttributes": {},
Expand Down
15 changes: 15 additions & 0 deletions docs/src/components/Demo/DemoLoader.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -254,6 +254,21 @@ function resolveExtensionlessFile(filePath: string, preferTs: boolean): string {
? ['.tsx', '.ts', '.jsx', '.js', '.json']
: ['.jsx', '.js', '.tsx', '.ts', '.json'];

if (existsSync(filePath)) {
const stats = statSync(filePath);
if (stats.isFile()) {
return filePath;
}
if (stats.isDirectory()) {
for (const extension of extensions) {
const indexPath = join(filePath, `index${extension}`);
if (existsSync(indexPath)) {
return indexPath;
}
}
}
}

for (const extension of extensions) {
const fullPath = `${filePath}${extension}`;
if (existsSync(fullPath)) {
Expand Down
14 changes: 14 additions & 0 deletions packages/react/src/alert-dialog/portal/AlertDialogPortal.test.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
import * as React from 'react';
import { AlertDialog } from '@base-ui-components/react/alert-dialog';
import { createRenderer, describeConformance } from '#test-utils';

describe('<AlertDialog.Portal />', () => {
const { render } = createRenderer();

describeConformance(<AlertDialog.Portal />, () => ({
refInstanceof: window.HTMLDivElement,
render(node) {
return render(<AlertDialog.Root open>{node}</AlertDialog.Root>);
},
}));
});
Loading
Loading