Popover

!npm (scoped)

#### View on MongoDB.design

Installation

$3

``shell
pnpm add @leafygreen-ui/popover
`

$3

`shell
yarn add @leafygreen-ui/popover
`

$3

`shell
npm install @leafygreen-ui/popover
`

Example

`tsx
import Popover, {
Align,
DismissMode,
Justify,
RenderMode,
ToggleEvent,
} from '@leafygreen-ui/popover';

const [open, setOpen] = useState(false);
const buttonRef = (useRef < HTMLButtonElement) | (null > null);

const handleClick = () => {
setOpen(open => !open);
};

const handleToggle = (e: ToggleEvent) => {
const newOpen = e.newState === 'open';
setOpen(newOpen);
};

<>

Open Popover

active={open}
align={Align.Bottom}
dismissMode={DismissMode.Auto}
justify={Justify.Start}
onToggle={handleToggle}
renderMode={RenderMode.TopLayer}
spacing={4}
adjustOnMutation
>
Popover content

;
`

Render mode

$3

In v12+ versions, a popover should now render in the top layer, which "appear[s] on top of all other content on the page."

The usePortal prop is available as an escape hatch to override the renderMode prop. usePortal can be used to render a popover positioned 'inline' relative to the nearest ancestor or in a 'portal'. RenderMode.Inline and RenderMode.Portal are marked deprecated and will eventually lose support. All overlay elements should migrate to using the top layer.

$3

In pre-v12 versions, a popover can be rendered in 2 ways using the usePortal prop. By default, usePortal={true}, and it is rendered in a portal. If usePortal={false}, it is rendered inline in the DOM.

Properties

| Prop | Type | Description | Default |
| ---------------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| active | boolean | Determines whether the Popover is active or inactive | false |
| adjustOnMutation | boolean | Should the Popover auto adjust its content when the DOM changes (using MutationObserver). | false |
| align | 'top' \| 'bottom' \| 'left' \| 'right' \| 'center-horizontal' \| 'center-vertical' | A string that determines the alignment of the popover relative to the refEl. | 'bottom' |
| children | node | Content that will appear inside of the component | |
| className | string | Classname to apply to popover-content container | |
| justify | 'start' \| 'middle' \| 'end' | A string that determines the justification of the popover relative to the refEl. Justification will be defined relative to the align prop | 'start' |
| onClick | function | Function that will be called when popover content is clicked. | |
| popoverZIndex (deprecated) | number | Sets the z-index CSS property for the popover. This will only apply if usePortal is defined and renderMode is not 'top-layer' | |
| refEl | React.RefObject | You can supply a refEl prop, if you do not want the popover to be positioned relative to it's nearest parent. Ref to the element to which the popover component should be positioned relative to. | null |
| spacing | number | Specifies the amount of spacing (in pixels) between the trigger element and the content element. | 4 |
| ... | native attributes of Portal or Fragment | Any other properties will be spread on the popover-content container | |

$3

| Prop | Type | Description | Default |
| ------------------------------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| dismissMode | 'auto' \| 'manual' | Options to control how the popover element is dismissed. This will only apply when renderMode is 'top-layer'
\ 'auto' will automatically handle dismissal on backdrop click or esc key press, ensuring only one popover is visible at a time
\ 'manual' will require that the consumer handle dismissal manually | 'auto' |
| onToggle | (e: ToggleEvent) => void; | Function that is called when the popover is toggled. This will only apply when renderMode is 'top-layer' | |
| portalClassName (deprecated) | string | Passes the given className to the popover's portal container if the default portal container is being used. This will only apply when renderMode is 'portal' | |
| portalContainer (deprecated) | HTMLElement \| null | Sets the container used for the popover's portal. This will only apply when renderMode is 'portal'.
NOTE: If using a scrollContainer make sure that the portalContainer is contained within the scrollContainer. E.g, passing the same reference to scrollContainer and portalContainer. | |
| portalRef (deprecated) | string | Passes a ref to forward to the portal element. This will only apply when renderMode is 'portal' | |
| scrollContainer (deprecated) | HTMLElement \| null | If the popover portal has a scrollable ancestor other than the window, this prop allows passing a reference to that element to allow the portal to position properly. This will only apply when renderMode is 'portal' | |
| renderMode | 'inline' \| 'portal' \| 'top-layer' | Options to render the popover element
\ [deprecated] 'inline' will render the popover element inline in the DOM where it's written
\ [deprecated] 'portal' will render the popover element in a new div appended to the body. Alternatively, can be portaled into a provided portalContainer
\* 'top-layer' will render the popover element in the top layer | 'top-layer' |

$3

| Prop | Type | Description | Default |
| ----------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| portalClassName | string | Passes the given className to the popover's portal container if the default portal container is being used. This will only apply when usePortal is true | |
| portalContainer | HTMLElement \| null | Sets the container used for the popover's portal. This will only apply when usePortal is true.
NOTE: If using a scrollContainer make sure that the portalContainer is contained within the scrollContainer. E.g, passing the same reference to scrollContainer and portalContainer. | |
| portalRef | string | Passes a ref to forward to the portal element. This will only apply when usePortal is true | |
| scrollContainer | HTMLElement \| null | If the popover portal has a scrollable ancestor other than the window, this prop allows passing a reference to that element to allow the portal to position properly. This will only apply when usePortal is true | |
| usePortal | boolean | Option to render popover element in a portal.
When true, the popover element will portal into the provided portalContainer or a new div appended to the end of the
When false, the popover element will render inline in the DOM | true` |