React Portals Explained

React Portals render children outside the parent DOM hierarchy while maintaining React's event system. Here's how to use them.

What Are Portals?#

import { createPortal } from 'react-dom';

function Modal({ children, isOpen }: { children: React.ReactNode; isOpen: boolean }) {
  if (!isOpen) return null;

  // Render children in document.body instead of parent
  return createPortal(
    <div className="modal-overlay">
      <div className="modal-content">
        {children}
      </div>
    </div>,
    document.body
  );
}

// Usage
function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div className="app">
      <button onClick={() => setIsOpen(true)}>Open Modal</button>

      {/* Modal renders in body, not inside .app */}
      <Modal isOpen={isOpen}>
        <h2>Modal Title</h2>
        <button onClick={() => setIsOpen(false)}>Close</button>
      </Modal>
    </div>
  );
}

Why Use Portals?#

// Problem: CSS overflow/z-index issues
function ProblematicParent() {
  return (
    <div style={{ overflow: 'hidden', position: 'relative' }}>
      {/* Dropdown gets clipped by parent's overflow */}
      <Dropdown>
        <DropdownMenu /> {/* This gets cut off! */}
      </Dropdown>
    </div>
  );
}

// Solution: Portal renders outside parent
function Dropdown({ children }: { children: React.ReactNode }) {
  const [isOpen, setIsOpen] = useState(false);
  const [position, setPosition] = useState({ top: 0, left: 0 });
  const buttonRef = useRef<HTMLButtonElement>(null);

  useEffect(() => {
    if (isOpen && buttonRef.current) {
      const rect = buttonRef.current.getBoundingClientRect();
      setPosition({
        top: rect.bottom + window.scrollY,
        left: rect.left + window.scrollX,
      });
    }
  }, [isOpen]);

  return (
    <>
      <button ref={buttonRef} onClick={() => setIsOpen(!isOpen)}>
        Toggle
      </button>

      {isOpen && createPortal(
        <div
          className="dropdown-menu"
          style={{ position: 'absolute', ...position }}
        >
          {children}
        </div>,
        document.body
      )}
    </>
  );
}

import { createPortal } from 'react-dom';
import { useEffect, useRef } from 'react';

interface ModalProps {
  isOpen: boolean;
  onClose: () => void;
  title?: string;
  children: React.ReactNode;
}

function Modal({ isOpen, onClose, title, children }: ModalProps) {
  const overlayRef = useRef<HTMLDivElement>(null);

  // Handle escape key
  useEffect(() => {
    const handleEscape = (e: KeyboardEvent) => {
      if (e.key === 'Escape') onClose();
    };

    if (isOpen) {
      document.addEventListener('keydown', handleEscape);
      document.body.style.overflow = 'hidden';
    }

    return () => {
      document.removeEventListener('keydown', handleEscape);
      document.body.style.overflow = '';
    };
  }, [isOpen, onClose]);

  // Handle click outside
  const handleOverlayClick = (e: React.MouseEvent) => {
    if (e.target === overlayRef.current) {
      onClose();
    }
  };

  if (!isOpen) return null;

  return createPortal(
    <div
      ref={overlayRef}
      className="modal-overlay"
      onClick={handleOverlayClick}
      role="dialog"
      aria-modal="true"
      aria-labelledby="modal-title"
    >
      <div className="modal-content">
        <header className="modal-header">
          {title && <h2 id="modal-title">{title}</h2>}
          <button
            onClick={onClose}
            aria-label="Close modal"
            className="modal-close"
          >
            ×
          </button>
        </header>
        <div className="modal-body">
          {children}
        </div>
      </div>
    </div>,
    document.body
  );
}

import { createPortal } from 'react-dom';
import { useState, useRef, useCallback } from 'react';

interface TooltipProps {
  content: React.ReactNode;
  children: React.ReactElement;
  position?: 'top' | 'bottom' | 'left' | 'right';
}

function Tooltip({ content, children, position = 'top' }: TooltipProps) {
  const [isVisible, setIsVisible] = useState(false);
  const [coords, setCoords] = useState({ top: 0, left: 0 });
  const triggerRef = useRef<HTMLElement>(null);

  const calculatePosition = useCallback(() => {
    if (!triggerRef.current) return;

    const rect = triggerRef.current.getBoundingClientRect();
    const scrollX = window.scrollX;
    const scrollY = window.scrollY;

    const positions = {
      top: {
        top: rect.top + scrollY - 8,
        left: rect.left + scrollX + rect.width / 2,
      },
      bottom: {
        top: rect.bottom + scrollY + 8,
        left: rect.left + scrollX + rect.width / 2,
      },
      left: {
        top: rect.top + scrollY + rect.height / 2,
        left: rect.left + scrollX - 8,
      },
      right: {
        top: rect.top + scrollY + rect.height / 2,
        left: rect.right + scrollX + 8,
      },
    };

    setCoords(positions[position]);
  }, [position]);

  const handleMouseEnter = () => {
    calculatePosition();
    setIsVisible(true);
  };

  const handleMouseLeave = () => {
    setIsVisible(false);
  };

  const trigger = React.cloneElement(children, {
    ref: triggerRef,
    onMouseEnter: handleMouseEnter,
    onMouseLeave: handleMouseLeave,
    onFocus: handleMouseEnter,
    onBlur: handleMouseLeave,
  });

  return (
    <>
      {trigger}
      {isVisible && createPortal(
        <div
          className={`tooltip tooltip-${position}`}
          style={{
            position: 'absolute',
            top: coords.top,
            left: coords.left,
            transform: position === 'top' || position === 'bottom'
              ? 'translateX(-50%)'
              : position === 'top'
              ? 'translateY(-100%)'
              : undefined,
          }}
          role="tooltip"
        >
          {content}
        </div>,
        document.body
      )}
    </>
  );
}

Notification Toast System#

import { createPortal } from 'react-dom';
import { createContext, useContext, useState, useCallback } from 'react';

interface Toast {
  id: string;
  message: string;
  type: 'success' | 'error' | 'info';
}

interface ToastContextType {
  addToast: (message: string, type?: Toast['type']) => void;
  removeToast: (id: string) => void;
}

const ToastContext = createContext<ToastContextType | null>(null);

export function ToastProvider({ children }: { children: React.ReactNode }) {
  const [toasts, setToasts] = useState<Toast[]>([]);

  const addToast = useCallback((message: string, type: Toast['type'] = 'info') => {
    const id = Date.now().toString();
    setToasts(prev => [...prev, { id, message, type }]);

    // Auto remove after 5 seconds
    setTimeout(() => {
      setToasts(prev => prev.filter(t => t.id !== id));
    }, 5000);
  }, []);

  const removeToast = useCallback((id: string) => {
    setToasts(prev => prev.filter(t => t.id !== id));
  }, []);

  return (
    <ToastContext.Provider value={{ addToast, removeToast }}>
      {children}
      {createPortal(
        <div className="toast-container" aria-live="polite">
          {toasts.map(toast => (
            <div
              key={toast.id}
              className={`toast toast-${toast.type}`}
              role="alert"
            >
              {toast.message}
              <button onClick={() => removeToast(toast.id)}>×</button>
            </div>
          ))}
        </div>,
        document.body
      )}
    </ToastContext.Provider>
  );
}

export function useToast() {
  const context = useContext(ToastContext);
  if (!context) {
    throw new Error('useToast must be used within ToastProvider');
  }
  return context;
}

Focus Management#

import { createPortal } from 'react-dom';
import { useEffect, useRef } from 'react';

function FocusTrapModal({ isOpen, onClose, children }: ModalProps) {
  const modalRef = useRef<HTMLDivElement>(null);
  const previousActiveElement = useRef<HTMLElement | null>(null);

  useEffect(() => {
    if (isOpen) {
      // Store current focus
      previousActiveElement.current = document.activeElement as HTMLElement;

      // Focus the modal
      modalRef.current?.focus();

      // Trap focus
      const handleTab = (e: KeyboardEvent) => {
        if (e.key !== 'Tab' || !modalRef.current) return;

        const focusableElements = modalRef.current.querySelectorAll(
          'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
        );
        const firstElement = focusableElements[0] as HTMLElement;
        const lastElement = focusableElements[focusableElements.length - 1] as HTMLElement;

        if (e.shiftKey && document.activeElement === firstElement) {
          e.preventDefault();
          lastElement.focus();
        } else if (!e.shiftKey && document.activeElement === lastElement) {
          e.preventDefault();
          firstElement.focus();
        }
      };

      document.addEventListener('keydown', handleTab);

      return () => {
        document.removeEventListener('keydown', handleTab);
        // Restore focus
        previousActiveElement.current?.focus();
      };
    }
  }, [isOpen]);

  if (!isOpen) return null;

  return createPortal(
    <div className="modal-overlay">
      <div
        ref={modalRef}
        className="modal-content"
        tabIndex={-1}
        role="dialog"
        aria-modal="true"
      >
        {children}
      </div>
    </div>,
    document.body
  );
}

Custom Portal Container#

import { createPortal } from 'react-dom';
import { useEffect, useState } from 'react';

function usePortalContainer(id: string) {
  const [container, setContainer] = useState<HTMLElement | null>(null);

  useEffect(() => {
    let element = document.getElementById(id);

    if (!element) {
      element = document.createElement('div');
      element.id = id;
      document.body.appendChild(element);
    }

    setContainer(element);

    return () => {
      // Only remove if empty
      if (element && element.childNodes.length === 0) {
        element.remove();
      }
    };
  }, [id]);

  return container;
}

function LayeredPortal({
  children,
  layer = 'modals',
}: {
  children: React.ReactNode;
  layer?: 'modals' | 'tooltips' | 'notifications';
}) {
  const container = usePortalContainer(`portal-${layer}`);

  if (!container) return null;

  return createPortal(children, container);
}

// CSS to manage layers
/*
#portal-modals { z-index: 1000; }
#portal-tooltips { z-index: 2000; }
#portal-notifications { z-index: 3000; }
*/

Event Bubbling#

// Events still bubble through React tree, not DOM tree
function ParentComponent() {
  const handleClick = (e: React.MouseEvent) => {
    console.log('Parent clicked');
    // This fires even though Modal is in document.body
  };

  return (
    <div onClick={handleClick}>
      <Modal isOpen={true}>
        <button>Click me</button>
        {/* Click bubbles to ParentComponent through React tree */}
      </Modal>
    </div>
  );
}

// Stop propagation if needed
function Modal({ children }: { children: React.ReactNode }) {
  return createPortal(
    <div onClick={(e) => e.stopPropagation()}>
      {children}
    </div>,
    document.body
  );
}

SSR Considerations#

import { createPortal } from 'react-dom';
import { useEffect, useState } from 'react';

function ClientPortal({ children }: { children: React.ReactNode }) {
  const [mounted, setMounted] = useState(false);

  useEffect(() => {
    setMounted(true);
  }, []);

  if (!mounted) return null;

  return createPortal(children, document.body);
}

// Or check for document
function SafePortal({ children }: { children: React.ReactNode }) {
  if (typeof document === 'undefined') {
    return null;
  }

  return createPortal(children, document.body);
}

Best Practices#

Accessibility:
✓ Manage focus properly
✓ Use correct ARIA attributes
✓ Handle keyboard navigation
✓ Restore focus on close

Performance:
✓ Don't overuse portals
✓ Clean up portal containers
✓ Lazy load modal content
✓ Use CSS animations

Architecture:
✓ Create reusable portal hooks
✓ Manage z-index consistently
✓ Handle SSR properly
✓ Consider event bubbling

UX:
✓ Block body scroll in modals
✓ Handle click outside
✓ Provide escape key handling
✓ Animate enter/exit

React Portals solve DOM hierarchy issues for modals, tooltips, and overlays. They maintain React's event system while rendering outside the parent. Use them when CSS constraints prevent proper rendering, always manage focus and accessibility, and handle SSR appropriately.