Skip to main content

Overview

Portal renders its children into a different part of the DOM, outside of the parent component’s DOM hierarchy. This is useful for rendering modals, dropdowns, tooltips, and other overlays.

Features

  • Renders content outside the parent DOM hierarchy
  • Can specify a custom container element
  • Automatically handles mounting/unmounting
  • Works with React portals under the hood

Installation

Anatomy

API Reference

Root

Portals content to a different part of the DOM.
HTMLElement | null
An optional container where the portaled content should be appended. If not provided, content is rendered to document.body.
React.ReactNode
The content to be portaled.

Examples

Basic Usage

Custom Container

When to Use

Use Portal when you need to:
  • Render modals and dialogs that should appear above all other content
  • Create dropdowns and menus that shouldn’t be clipped by parent overflow
  • Build tooltips that need to escape parent containers
  • Render notifications at the document root level
  • Create overlays that span the entire viewport

How It Works

Portal uses React’s createPortal API to render children into a DOM node that exists outside the parent component’s DOM hierarchy. This is particularly useful for:
  • Avoiding z-index issues: Content portaled to the body can be easily stacked above other content
  • Escaping overflow clipping: Parent containers with overflow: hidden won’t clip portaled content
  • Managing focus: Modals and dialogs can manage focus independently of their parent

Server-Side Rendering

Portal is compatible with server-side rendering. It waits until the component is mounted on the client before rendering its children, preventing hydration mismatches.