@chakra-ui/portal

What is @chakra-ui/portal?

@chakra-ui/portal is a package that provides a way to render components outside the main DOM hierarchy. This is particularly useful for creating modals, tooltips, and other UI elements that need to be rendered in a different part of the DOM tree to avoid clipping or other layout issues.

What are @chakra-ui/portal's main functionalities?

Basic Portal Usage

This example demonstrates the basic usage of the Portal component. The content inside the Portal is rendered outside the main DOM hierarchy, which can be useful for avoiding layout issues.

import { Portal } from '@chakra-ui/portal';
import { Box, Button } from '@chakra-ui/react';

function App() {
  return (
    <Box>
      <Button>Click me</Button>
      <Portal>
        <Box position="absolute" top="50px" left="50px" bg="tomato" p={4}>
          This is a portal content
        </Box>
      </Portal>
    </Box>
  );
}

export default App;

Nested Portals

This example demonstrates the usage of nested portals. The nested portal content is rendered outside the main DOM hierarchy and also outside the parent portal's DOM hierarchy.

import { Portal } from '@chakra-ui/portal';
import { Box, Button } from '@chakra-ui/react';

function App() {
  return (
    <Box>
      <Button>Click me</Button>
      <Portal>
        <Box position="absolute" top="50px" left="50px" bg="tomato" p={4}>
          This is a portal content
          <Portal>
            <Box position="absolute" top="20px" left="20px" bg="blue" p={4}>
              Nested portal content
            </Box>
          </Portal>
        </Box>
      </Portal>
    </Box>
  );
}

export default App;

Conditional Rendering with Portal

This example demonstrates conditional rendering with the Portal component. The portal content is rendered only when the state `isOpen` is true.

import { useState } from 'react';
import { Portal } from '@chakra-ui/portal';
import { Box, Button } from '@chakra-ui/react';

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

  return (
    <Box>
      <Button onClick={() => setIsOpen(!isOpen)}>Toggle Portal</Button>
      {isOpen && (
        <Portal>
          <Box position="absolute" top="50px" left="50px" bg="tomato" p={4}>
            This is a portal content
          </Box>
        </Portal>
      )}
    </Box>
  );
}

export default App;

Other packages similar to @chakra-ui/portal

react-portal

react-portal is a package that provides a simple way to render children into a DOM node that exists outside the DOM hierarchy of the parent component. It is similar to @chakra-ui/portal in that it allows for rendering components outside the main DOM tree, but it is more lightweight and does not come with the additional UI components that Chakra UI provides.

react-dom

react-dom is a core package from the React library that includes the createPortal function. This function allows you to render children into a DOM node that exists outside the DOM hierarchy of the parent component. It is a lower-level API compared to @chakra-ui/portal and requires more manual setup.

react-overlays

react-overlays is a library that provides a set of components for creating overlays, including modals, tooltips, and popovers. It includes a Portal component similar to @chakra-ui/portal but also provides additional components and utilities for managing overlays.

README

@chakra-ui/portal

A wrapper for rendering components in React Portals, with support for nested portals and stacking. No need to use z-index at all with this portal, that's right!

Installation

yarn add @chakra-ui/portal

# or

npm i @chakra-ui/portal

Import components

import { Portal, PortalManager } from "@chakra-ui/portal"

Render the PortalManager once at the root of your application

function App() {
  return (
    <ThemeProvider>
      <CSSReset />
      <PortalManager>{/* Your app goes here  */}</PortalManager>
    </ThemeProvider>
  )
}

Basic usage

Portals are render into the portal manager's node by default not document.body.

It'll only render into document.body if you don't include PortalManager.

<div>
  <p>Welcome</p>
  <Portal>This text has been portaled</Portal>
</div>

Nested portals

Nesting portal can be very useful to build complex widgets like nested menu, popovers, modal, etc.

<Portal>
  This is a portal.
  <Portal>This is a nested portal</Portal>
</Portal>

Custom container

You can also portal elements into a custom containers. Simply pass a container prop that points to the node of that element.

<>
  <div data-testid="container" ref={ref} />
  <Portal container={() => ref.current}>
    <h1 data-testid="heading">Hello world</h1>
  </Portal>
</>