# Portal
> Utility component to help with the React createPortal API.

## Import

```js
import { Portal, usePortal } from '@volue/wave-react';
```

## Portals in a nutshell

Portals are used to transport any component or element to the end of `document.body` and render a React tree into them.

They are useful for rendering a natural React element hierarchy with a different DOM hierarchy to prevent parent styles from clipping or hiding content (for popovers, dropdowns, dialogs etc).

## Examples

### Basic

```jsx
<Box
  css={{
    backgroundColor: '$backgroundNeutralStrong',
    color: '$foregroundInverse'
  }}
>
  {`I'm here,`}
  <Portal>
    <Box css={{ color: '$foregroundInverse' }}>{'I am in a portal!'}</Box>
  </Portal>
</Box>
```

### Nesting portals

You can also nest multiple portals within themselves, this will create a nested DOM hierarchy to make it easy to create nested dialogs, popovers, etc.

```jsx
() => {
  const ref = React.useRef();

  return (
    <div>
      <Box
        css={{
          backgroundColor: '$backgroundNeutral',
          padding: '$spacingS'
        }}
        ref={ref}
      />
      <Portal containerRef={ref}>
        <Box
          css={{
            backgroundColor: '$backgroundNeutralContrast',
            color: '$foregroundInverse',
            padding: '$spacingS'
          }}
        >
          {'Parent: Hey welcome,'}
          <Portal>{`Child: I'm attached to my parent portal`}</Portal>
        </Box>
      </Portal>
    </div>
  );
};
```

---

## API reference

| Name           | Type                      | Default | Description                                                      | Required |
| -------------- | ------------------------- | ------- | ---------------------------------------------------------------- | -------- |
| `containerRef` | `Unreffable<HTMLElement>` |         | The `ref` to the component where the portal will be attached to. |          |