# PortalProvider

**📖 Live documentation:** https://cds.coinbase.com/components/overlay/PortalProvider/

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

## Import

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

## Examples

### Basic usage

Render PortalProvider once near the root of your application:

```tsx live
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:

```tsx live
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:

```tsx live
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>
  );
}
```

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `renderPortals` | `boolean` | No | `true` | By default the PortalProvider will render portal nodes. Disable this if you want to use the PortalNodes component to render the nodes instead. |
| `toastBottomOffset` | `string \| number` | No | `-` | An optional, global override to individual Toasts bottomOffset prop. This value will be applied to all Toasts render via this Provider instance |


