PortalProvider

@coinbase/cds-web@9.0.2

A required root-level provider that creates the DOM containers for CDS overlay components (Modal, Toast, Alert, Tooltip, Tray) and manages overlay state.

import { PortalProvider } from '@coinbase/cds-web/overlays/PortalProvider'

󰒨

Source

󰏖

Storybook

󰏖

View as Markdown

---

Peer dependencies

• react-dom: ^18.0.0 || ~19.1.2

---

Related components

• Modal,
• Toast,
• Alert

Basic usage

Render PortalProvider once near the root of your application:

Loading...

󰙡

Live Code

function Example() {
  return (
    <PortalProvider>
      <Box padding={4} bordered borderRadius={200}>
        Your app content
      </Box>
    </PortalProvider>
  );
}

Custom Portal Nodes

You can disable the default portal rendering and use the PortalNodes component separately:

Loading...

󰙡

Live Code

function Example() {
  return (
    <PortalProvider renderPortals={false}>
      <Box padding={4} bordered borderRadius={200}>
        Your app content
      </Box>
      <PortalNodes />
    </PortalProvider>
  );
}

Toast Example

The PortalProvider's toastBottomOffset prop sets the default bottom offset for all toasts:

Loading...

󰙡

Live Code

function Example() {
  function ToastDemo() {
    const toast = useToast();
    return (
      <Box padding={4} bordered borderRadius={200}>
        <Button onClick={() => toast.show('This toast appears with a custom bottom offset (80px)')}>
          Show Toast
        </Button>
      </Box>
    );
  }

  return (
    <PortalProvider toastBottomOffset={80}>
      <ToastDemo />
    </PortalProvider>
  );
}