Popover

The Popover component is an overlay element positioned relative to a trigger element.

Installation

npm install --save @godaddy/antares

Props

NameTypeDefault

children?ReactNode—

The content to display inside the popover.

showCloseButton?boolean | undefined—

Whether to show the close button.

contentProps?Omit<FlexProps, "as" | "role"> | undefined—

Props to pass to the content container.

placement?Placement | undefined'bottom'

The placement of the popover relative to the trigger.

hideArrow?boolean | undefined—

Whether to hide the arrow.

header?ReactNode—

The content to display in the header when `showCloseButton` is `true`.

triggerRef?RefObject<Element | null> | undefined—

The ref for the element which the popover positions itself with respect to. When used within `PopoverTrigger` component, this is set automatically.

className?ClassNameOrFunction<PopoverRenderProps> | undefined'react-aria-Popover'

The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state.

trigger?string | undefined—

The name of the component that triggered the popover. This is reflected on the element as the `data-trigger` attribute, and can be used to provide specific styles for the popover depending on which element triggered it.

isEntering?boolean | undefined—

Whether the popover is currently performing an entry animation.

isExiting?boolean | undefined—

Whether the popover is currently performing an exit animation.

UNSTABLE_portalContainer?Element | undefineddocument.body

The container element in which the overlay portal will be placed. This may have unknown behavior depending on where it is portalled to.

offset?number | undefined8

The additional offset applied along the main axis between the element and its anchor element.

containerPadding?number | undefined12

The placement padding that should be applied between the element and its surrounding container.

crossOffset?number | undefined0

The additional offset applied along the cross axis between the element and its anchor element.

shouldFlip?boolean | undefinedtrue

Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely.

boundaryElement?Element | undefineddocument.body

Element that that serves as the positioning boundary.

arrowRef?RefObject<Element | null> | undefined—

A ref for the popover arrow element.

scrollRef?RefObject<Element | null> | undefinedoverlayRef

A ref for the scrollable region within the overlay.

shouldUpdatePosition?boolean | undefinedtrue

Whether the overlay should update its position automatically.

maxHeight?number | undefined—

The maxHeight specified for the overlay element. By default, it will take all space up to the current viewport height.

arrowBoundaryOffset?number | undefined0

The minimum distance the arrow's edge should be from the edge of the overlay element.

isNonModal?boolean | undefined—

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 | undefinedfalse

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) | undefined—

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.

isOpen?boolean | undefined—

Whether the overlay is open by default (controlled).

defaultOpen?boolean | undefined—

Whether the overlay is open by default (uncontrolled).

onOpenChange?((isOpen: boolean) => void) | undefined—

Handler that is called when the overlay's open state changes.

style?StyleOrFunction<PopoverRenderProps> | undefined—

The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state.

render?DOMRenderFunction<"div", PopoverRenderProps> | undefined—

Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.

slot?string | null | undefined—

A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.

Examples

Basic Usage

Use it with <PopoverTrigger>, which wraps both the popover content and an interactive trigger element (for example, a Button).

import { Popover, PopoverTrigger, Button } from '@godaddy/antares';export function DefaultExample() {  return (    <PopoverTrigger>      <Button variant="primary">Open popover</Button>      <Popover>This is the popover content!</Popover>    </PopoverTrigger>  );}

Custom Anchor

To position a popover relative to a different element than its trigger, use the triggerRef and isOpen props instead of <PopoverTrigger>. onOpenChange is called when the user opens or closes the popover.

Popover will be positioned relative to me

import { Popover, Box, Flex, Button } from '@godaddy/antares';import { useRef, useState } from 'react';export function CustomAnchorExample() {  const [isOpen, setOpen] = useState(false);  const triggerRef = useRef<HTMLDivElement>(null);  return (    <Flex gap="sm" alignItems="center">      <Button variant="primary" onPress={() => setOpen(true)}>        Open Popover      </Button>      <Box elevation="card" ref={triggerRef}>        Popover will be positioned relative to me      </Box>      <Popover triggerRef={triggerRef} isOpen={isOpen} onOpenChange={setOpen}>        Popover content!      </Popover>    </Flex>  );}

Close Button and Header

To show a close button in the popover header, use the showCloseButton prop.

You can also use the header prop to render content alongside the close button. This is useful for displaying a title or other header content without overlapping the close button.

import { Popover, PopoverTrigger, Button, Text } from '@godaddy/antares';export function WithCloseButtonExample() {  return (    <PopoverTrigger>      <Button variant="primary">Open popover</Button>      <Popover showCloseButton header={<Text>Content to show next to the close button</Text>}>        This is the popover content!      </Popover>    </PopoverTrigger>  );}

Best Practices

Popover width is determined by its content, and it’s recommended to keep it under 400px.