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

## Import

```js
import { Portal, usePortal } from '@gemini-suite/vera-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: '$colorAccent80', color: 'white' }}>
  {`I'm here,`}
  <Portal>
    <Box css={{ color: 'white' }}>{'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>
      <Portal containerRef={ref}>
        <Box
          css={{
            backgroundColor: '$colorGray100',
            color: 'white',
            padding: '$spacingS'
          }}
        >
          {'Parent: Hey welcome,'}
          <Portal>{`Child: I'm attached to my parent portal`}</Portal>
        </Box>
      </Portal>
      <Box
        css={{
          backgroundColor: '$colorAccent90',
          color: 'white',
          padding: '$spacingS'
        }}
        ref={ref}
      />
    </div>
  );
};
```

---

## API Reference

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