React Portals Guide

React Portals render children into a DOM node outside the parent component's hierarchy. Here's how to use them.

Basic Portal#

import { createPortal } from 'react-dom';

function Modal({ children, isOpen }) {
  if (!isOpen) return null;

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

// Usage
function App() {
  const [showModal, setShowModal] = useState(false);

  return (
    <div>
      <button onClick={() => setShowModal(true)}>
        Open Modal
      </button>
      <Modal isOpen={showModal}>
        <h2>Modal Title</h2>
        <p>Modal content here</p>
        <button onClick={() => setShowModal(false)}>
          Close
        </button>
      </Modal>
    </div>
  );
}

Portal Container#

// Create a dedicated portal root
// In public/index.html:
// <div id="portal-root"></div>

function Portal({ children }) {
  const [container] = useState(() => {
    const el = document.createElement('div');
    el.className = 'portal-container';
    return el;
  });

  useEffect(() => {
    const portalRoot = document.getElementById('portal-root');
    portalRoot?.appendChild(container);

    return () => {
      portalRoot?.removeChild(container);
    };
  }, [container]);

  return createPortal(children, container);
}

// Usage
function Tooltip({ children, content, position }) {
  const [show, setShow] = useState(false);

  return (
    <div
      onMouseEnter={() => setShow(true)}
      onMouseLeave={() => setShow(false)}
    >
      {children}
      {show && (
        <Portal>
          <div className="tooltip" style={position}>
            {content}
          </div>
        </Portal>
      )}
    </div>
  );
}

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

function Modal({ isOpen, onClose, children, title }) {
  // Handle escape key
  const handleEscape = useCallback((e: KeyboardEvent) => {
    if (e.key === 'Escape') {
      onClose();
    }
  }, [onClose]);

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

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

  if (!isOpen) return null;

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

// Styles
const styles = `
  .modal-overlay {
    position: fixed;
    inset: 0;
    background: rgba(0, 0, 0, 0.5);
    display: flex;
    align-items: center;
    justify-content: center;
    z-index: 1000;
  }

  .modal-content {
    background: white;
    border-radius: 8px;
    max-width: 500px;
    width: 90%;
    max-height: 90vh;
    overflow: auto;
  }
`;

function Dropdown({ trigger, items, onSelect }) {
  const [isOpen, setIsOpen] = useState(false);
  const [position, setPosition] = useState({ top: 0, left: 0 });
  const triggerRef = useRef<HTMLButtonElement>(null);

  const updatePosition = useCallback(() => {
    if (triggerRef.current) {
      const rect = triggerRef.current.getBoundingClientRect();
      setPosition({
        top: rect.bottom + window.scrollY,
        left: rect.left + window.scrollX,
      });
    }
  }, []);

  useEffect(() => {
    if (isOpen) {
      updatePosition();
      window.addEventListener('scroll', updatePosition);
      window.addEventListener('resize', updatePosition);
    }

    return () => {
      window.removeEventListener('scroll', updatePosition);
      window.removeEventListener('resize', updatePosition);
    };
  }, [isOpen, updatePosition]);

  // Close on outside click
  useEffect(() => {
    const handleClick = (e: MouseEvent) => {
      if (!triggerRef.current?.contains(e.target as Node)) {
        setIsOpen(false);
      }
    };

    if (isOpen) {
      document.addEventListener('click', handleClick);
    }

    return () => {
      document.removeEventListener('click', handleClick);
    };
  }, [isOpen]);

  return (
    <>
      <button
        ref={triggerRef}
        onClick={() => setIsOpen(!isOpen)}
      >
        {trigger}
      </button>

      {isOpen && createPortal(
        <ul
          className="dropdown-menu"
          style={{
            position: 'absolute',
            top: position.top,
            left: position.left,
          }}
        >
          {items.map((item, i) => (
            <li key={i}>
              <button onClick={() => {
                onSelect(item);
                setIsOpen(false);
              }}>
                {item.label}
              </button>
            </li>
          ))}
        </ul>,
        document.body
      )}
    </>
  );
}

Toast Notifications#

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

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

const ToastContext = createContext<{
  addToast: (message: string, type: Toast['type']) => void;
} | null>(null);

function ToastProvider({ children }) {
  const [toasts, setToasts] = useState<Toast[]>([]);

  const addToast = useCallback((message: string, type: Toast['type']) => {
    const id = Math.random().toString(36).slice(2);
    setToasts(prev => [...prev, { id, message, type }]);

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

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

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

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

// Usage
function App() {
  return (
    <ToastProvider>
      <MyComponent />
    </ToastProvider>
  );
}

function MyComponent() {
  const { addToast } = useToast();

  return (
    <button onClick={() => addToast('Saved!', 'success')}>
      Save
    </button>
  );
}

Focus Management#

import { useRef, useEffect } from 'react';

function FocusTrap({ children, isActive }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const previousFocus = useRef<HTMLElement | null>(null);

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

      // Focus first focusable element
      const focusable = containerRef.current?.querySelectorAll(
        'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
      );

      if (focusable?.length) {
        (focusable[0] as HTMLElement).focus();
      }

      return () => {
        // Restore focus when unmounting
        previousFocus.current?.focus();
      };
    }
  }, [isActive]);

  const handleKeyDown = (e: React.KeyboardEvent) => {
    if (e.key !== 'Tab') return;

    const focusable = containerRef.current?.querySelectorAll(
      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
    );

    if (!focusable?.length) return;

    const first = focusable[0] as HTMLElement;
    const last = focusable[focusable.length - 1] as HTMLElement;

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

  return (
    <div ref={containerRef} onKeyDown={handleKeyDown}>
      {children}
    </div>
  );
}

// Usage with Modal
function AccessibleModal({ isOpen, onClose, children }) {
  if (!isOpen) return null;

  return createPortal(
    <FocusTrap isActive={isOpen}>
      <div className="modal-overlay" onClick={onClose}>
        <div
          className="modal-content"
          onClick={(e) => e.stopPropagation()}
          role="dialog"
          aria-modal="true"
        >
          {children}
        </div>
      </div>
    </FocusTrap>,
    document.body
  );
}

Event Bubbling#

// Events still bubble through React tree, not DOM tree
function Parent() {
  const handleClick = () => {
    console.log('Parent clicked!');
  };

  return (
    <div onClick={handleClick}>
      <Child />
    </div>
  );
}

function Child() {
  return createPortal(
    <button>
      Click me (event bubbles to Parent!)
    </button>,
    document.body
  );
}

// To prevent bubbling
function ChildWithStopPropagation() {
  return createPortal(
    <button onClick={(e) => e.stopPropagation()}>
      Click me (event does NOT bubble)
    </button>,
    document.body
  );
}

SSR Considerations#

// Portal that works with SSR
function SafePortal({ children }) {
  const [mounted, setMounted] = useState(false);

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

  if (!mounted) {
    return null;
  }

  return createPortal(children, document.body);
}

// Or check for document
function Portal({ children, container }) {
  if (typeof document === 'undefined') {
    return null;
  }

  return createPortal(
    children,
    container || document.body
  );
}

Best Practices#

Use Portals For:
✓ Modals and dialogs
✓ Tooltips and popovers
✓ Dropdown menus
✓ Toast notifications

Accessibility:
✓ Manage focus properly
✓ Use focus traps in modals
✓ Include ARIA attributes
✓ Handle escape key

Event Handling:
✓ Remember events bubble through React tree
✓ Stop propagation when needed
✓ Clean up event listeners

Avoid:
✗ Overusing portals for simple cases
✗ Forgetting cleanup in useEffect
✗ Ignoring SSR compatibility
✗ Breaking accessibility

React Portals are essential for rendering UI that needs to visually "break out" of its container, like modals, tooltips, and dropdowns. Events still bubble through the React tree, and context works normally. Always manage focus properly and ensure accessibility when using portals for interactive content.