usePopover

Provides the behavior and accessibility implementation for a popover component. A popover is an overlay element positioned relative to a trigger.

Example

Popover.tsx

Popover.css

Button.css

Dialog.css

Example

Popover.tsx

Popover.css

Button.css

Dialog.css

import {Dialog, Heading} from 'react-aria-components/Dialog';
import {PopoverTrigger} from './Popover';

<PopoverTrigger label="Open popover" placement="bottom">
  <Dialog>
    <Heading slot="title">Popover title</Heading>
    <p style={{margin: 0}}>This is the content of the popover.</p>
  </Dialog>
</PopoverTrigger>

Note: usePopover only handles the overlay itself. It should be combined with useDialog to create fully accessible popovers. Other overlays such as menus may also be placed in a popover.

API

<DialogTrigger>
  <Button />
  <Popover>
    <OverlayArrow />
  </Popover>
</DialogTrigger>

useOverlayTriggerState(props: OverlayTriggerProps): OverlayTriggerState

useOverlayTrigger(
  props: OverlayTriggerProps,
state: OverlayTriggerState,
ref?: RefObject<Element | null>
): OverlayTriggerAria

usePopover(props: AriaPopoverProps, state: OverlayTriggerState): PopoverAria

OverlayTriggerState

Properties

Name	Type
`point`	`Point \| null`
The cursor position when the overlay was triggered, relative to the window viewport.

Methods

`setOpen(isOpen: boolean): void`
Sets whether the overlay is open.
`open(): void`
Opens the overlay.
`close(): void`
Closes the overlay.
`toggle(): void`
Toggles the overlay's visibility.
`setPoint(point: Point): void`
Sets the cursor position relative to the window viewport.

AriaPopoverProps

Name	Type	Default
`triggerRef`	`RefObject<Element \| null>`	Default: —
The ref for the element which the popover positions itself with respect to.
`popoverRef`	`RefObject<Element \| null>`	Default: —
The ref for the popover element.
`arrowRef`	`RefObject<Element \| null>`	Default: —
A ref for the popover arrow element.
`groupRef`	`RefObject<Element \| null>`	Default: —
An optional ref for a group of popovers, e.g. submenus. When provided, this element is used to detect outside interactions and hiding elements from assistive technologies instead of the popoverRef.
`isNonModal`	`boolean`	Default: —
Whether the popover is non-modal, i.e. elements outside the popover may be interacted with by assistive technologies. Most popovers should not use this option as it may negatively impact the screen reader experience. Only use with components such as combobox, which are designed to handle this situation carefully.
`isKeyboardDismissDisabled`	`boolean`	Default: `false`
Whether pressing the escape key to close the popover should be disabled. Most popovers should not use this option. When set to true, an alternative way to close the popover with a keyboard must be provided.
`shouldCloseOnInteractOutside`	`(element: Element) => boolean`	Default: —
When user interacts with the argument element outside of the popover ref, return true if onClose should be called. This gives you a chance to filter out interaction with elements that should not dismiss the popover. By default, onClose will always be called on interaction outside the popover ref.
`arrowSize`	`number`	Default: `0`
Cross size of the overlay arrow in pixels.
`boundaryElement`	`Element`	Default: `document.body`
Element that that serves as the positioning boundary.
`scrollRef`	`RefObject<Element \| null>`	Default: `overlayRef`
A ref for the scrollable region within the overlay.
`shouldUpdatePosition`	`boolean`	Default: `true`
Whether the overlay should update its position automatically.
`maxHeight`	`number`	Default: —
The maxHeight specified for the overlay element. By default, it will take all space up to the current viewport height.
`arrowBoundaryOffset`	`number`	Default: `0`
The minimum distance the arrow's edge should be from the edge of the overlay element.
`getTargetRect`	`(target: Element) => DOMRect \| null \| undefined`	Default: `target.getBoundingClientRect()`
Overrides the target element's bounding rectangle. Useful for positioning relative to a specific point such as the mouse cursor (e.g. context menus) or text selection.
`placement`	`Placement`	Default: `'bottom'`
The placement of the element with respect to its anchor element.

PopoverAria

Name	Type
`popoverProps`	`DOMAttributes`
Props for the popover element.
`arrowProps`	`DOMAttributes`
Props for the popover tip arrow if any.
`underlayProps`	`DOMAttributes`
Props to apply to the underlay element, if any.
`placement`	`PlacementAxis \| null`
Placement of the popover with respect to the trigger.
`triggerAnchorPoint`	`{'x': number, 'y': number } \| null`
The origin of the target in the overlay's coordinate system. Useful for animations.