# Portal

Renders children into another element, `document.body` by default. `PortalProvider` sets that element for every Mosaic overlay below it, and `useGetPortalContainer` reads it back.

## Use for

- rendering an overlay outside its parent’s clipping or stacking context
- portalling every Mosaic overlay into one container instead of `document.body`
- a modal host that must hold its own popovers and menus

## Practices

- Do: Set the container once with `PortalProvider`, instead of passing `root` to each overlay’s portal.
- Do: Call `useGetPortalContainer` when code that mounts its own UI needs the container. It returns `undefined` without a provider.

## API reference

### Portal

Portals its children through Floating UI’s `FloatingPortal`. Inside another `Portal`, it ignores the provider’s container.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `root` | `PortalContainer` | `` the `PortalProvider` container, else `document.body` `` | The element or ref to portal into. |

### PortalProvider

Sets where Mosaic overlays below it portal to. Overlays wait until the container exists.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `PortalContainer` |  | The element or ref to portal into. |

## Examples

### Overlays in a host element

```tsx
const host = useRef<HTMLDivElement>(null);

<div ref={host} />
<PortalProvider container={host}>{children}</PortalProvider>
```

## Related

- [Popover](/docs/components/popover.md)
- [Menu](/docs/components/menu.md)
- [Tooltip](/docs/components/tooltip.md)
- [Toast](/docs/primitives/toast.md)
