Portal

An unstyled utility component that renders content into a DOM node outside the component hierarchy.

Build fully custom overlay containers with SSR-safe portal rendering.

Portal Target

basic-demo

For hook-based usage without components, see the usePortal hook.

Features#

SSR-safe rendering that waits for client-side mount before creating portals
Flexible appendTo targeting: 'body', 'self', HTMLElement, CSS selector, or a function
Accepts children, element prop, or elementRef as content source

Usage#

import { Portal } from 'primereact/portal';

<Portal>
    <div></div>
</Portal>

Behavior#

Polymorphic Rendering#

Portal does not render a wrapper element. Content is portaled directly into the target container.

Render Function Children#

Portal accepts a render function as children, providing access to the component instance.

<Portal>{(instance) => <div>{instance.state.mounted ? 'Mounted' : 'Pending'}</div>}</Portal>

API#

Portal#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: PortalInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: PortalInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`PortalInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<PortalPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: PortalInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`onMounted`	`() => void`	—
Callback function to invoke when the portal is mounted.
`onUnmounted`	`() => void`	—
Callback function to invoke when the portal is unmounted.
`element`	`HTMLElement` \| `ReactNode`	—
The element to be rendered as the portal.
`elementRef`	`RefObject<HTMLElement>`	—
The element reference to be rendered as the portal.
`appendTo`	`string` \| `HTMLElement` \| `((instance: PortalInstance) => HTMLElement)`	`'body'`
The DOM element where the portal should be appended to.
`[key: string]`	`any`	—

Accessibility#

Portal is a structural utility that renders content into a different DOM location. It does not introduce any ARIA roles or keyboard interactions. Accessibility concerns are handled by the content rendered inside the portal (e.g., Popover.Popup, Drawer.Portal).