## Import

```jsx
import { Popover } from "@cfa/react-core";
```

## Live Editor

```jsx
<Popover.Root>
  <Button>Popover Trigger</Button>
  <Popover.Panel>
    <div style={{ display: "flex", flexDirection: "column", gap: "16px" }}>
      <Switch>Switch 1</Switch>
      <Switch>Switch 2</Switch>
      <Button size="sm" variant="tertiary">
        Submit
      </Button>
    </div>
  </Popover.Panel>
</Popover.Root>
```

## Guidelines

### When to use

- Popover is for secondary information or controls people open from an anchored trigger.

### Do

- Close on action selection when the popover lists actions or links.
- When edits are not committed live, include Apply and Cancel in the footer. Close on Apply, not on outside click during edit.

### Avoid

- Putting long forms or critical actions in a Popover. Use Modal.
- Opening a Popover automatically on page load. Popovers are opt-in.
- Using Popover for a list of menu actions. Use Menu.
- Using Popover for a brief, non-interactive hint on hover or focus. Use Tooltip.

## Examples

### Default Popover

A basic example of the Popover component with a trigger and a panel.

```jsx
<Popover.Root>
  <Button>Popover Trigger</Button>
  <Popover.Panel>
    <div style={{ display: "flex", flexDirection: "column", gap: "16px" }}>
      <Switch>Switch 1</Switch>
      <Switch>Switch 2</Switch>
      <Button size="sm" variant="tertiary">
        Submit
      </Button>
    </div>
  </Popover.Panel>
</Popover.Root>
```

### Hover Root

Use `Popover.HoverRoot` to open a non-modal popover on hover, keyboard focus, or long press. Unlike `Tooltip`, hover popovers can include interactive content such as links and buttons.

Previews appear after a warmup delay. Once a preview is displayed, other previews display immediately. If the user waits for the cooldown period before hovering another element, the warmup timer restarts. When a preview is open, Tab moves focus into the popover so users can interact with its contents. Press Escape to close the preview and return focus to the trigger.

Use a focusable trigger such as `Link` or `Button`. Pass `inline` on `Link` when the trigger sits in paragraph text.

```jsx
<Popover.HoverRoot>
  <Button>Popover Trigger</Button>
  <Popover.Panel>
    <div style={{ display: "flex", flexDirection: "column", gap: "16px" }}>
      <Switch>Switch 1</Switch>
      <Switch>Switch 2</Switch>
      <Button size="sm" variant="tertiary">
        Submit
      </Button>
    </div>
  </Popover.Panel>
</Popover.HoverRoot>
```

### Custom Trigger

Using a custom trigger element wrapped in a `Pressable` component.

```jsx
<Popover.Root>
  <Pressable>
    <span role="button">Custom trigger</span>
  </Pressable>
  <Popover.Panel>
    <div style={{ display: "flex", flexDirection: "column", gap: "16px" }}>
      <Switch>Switch 1</Switch>
      <Switch>Switch 2</Switch>
      <Button size="sm" variant="tertiary">
        Submit
      </Button>
    </div>
  </Popover.Panel>
</Popover.Root>
```

### Placement

You can control the position of the popover relative to its trigger using the `placement` prop. The default placement is `bottom`.

```jsx
<div style={{ display: "flex", justifyContent: "space-between" }}>
  <Popover.Root>
    <Button>Top Placement</Button>
    <Popover.Panel placement="top">This popover appears above the trigger</Popover.Panel>
  </Popover.Root>

  <Popover.Root>
    <Button>Right Placement</Button>
    <Popover.Panel placement="right">
      This popover appears to the right of the trigger
    </Popover.Panel>
  </Popover.Root>

  <Popover.Root>
    <Button>Bottom Placement</Button>
    <Popover.Panel placement="bottom">
      This popover appears below the trigger (default)
    </Popover.Panel>
  </Popover.Root>

  <Popover.Root>
    <Button>Left Placement</Button>
    <Popover.Panel placement="left">This popover appears to the left of the trigger</Popover.Panel>
  </Popover.Root>
</div>
```

### Composition

The Popover component offers two different ways to use it. The simplified `Popover.Panel` approach (recommended) or the more granular approach using `Popover.Wrapper` and `Popover.Dialog`.

#### Recommended: Popover.Panel

For most use cases, we recommend using `Popover.Panel`. It combines the `Wrapper` and `Dialog` components into a single, convenient component.

```jsx
<Popover.Root>
  <Button>Simplified Approach</Button>
  <Popover.Panel>This is the recommended way to use Popover</Popover.Panel>
</Popover.Root>
```

#### Alternative: Wrapper & Dialog

For advanced use cases where you need more control over the structure, you can use the `Wrapper` and `Dialog` components directly. However, this is generally not necessary and adds complexity.

```jsx
<Popover.Root>
  <Button>Granular Approach</Button>
  <Popover.Wrapper>
    <Popover.Dialog>
      This approach gives more granular control but is more verbose and rarely needed
    </Popover.Dialog>
  </Popover.Wrapper>
</Popover.Root>
```

### Events

The Popover component provides an `onOpenChange` event that allows you to track and control when the popover opens or closes.

```jsx
function PopoverWithEvents() {
  const [isOpen, setIsOpen] = React.useState(false);
  const [eventLog, setEventLog] = React.useState("Popover is closed");

  const handleOpenChange = (open) => {
    setIsOpen(open);
    setEventLog(`Popover is ${open ? "open" : "closed"} at ${new Date().toLocaleTimeString()}`);
  };

  return (
    <div>
      <div style={{ marginBottom: "16px" }}>
        <strong>Status:</strong> {eventLog}
      </div>
      <Popover.Root isOpen={isOpen} onOpenChange={handleOpenChange}>
        <Button>Controlled Popover</Button>
        <Popover.Panel>
          <div style={{ display: "flex", flexDirection: "column", gap: "16px" }}>
            <div>This popover is controlled by state</div>
            <Button size="sm" variant="tertiary" onPress={() => handleOpenChange(false)}>
              Close Popover
            </Button>
          </div>
        </Popover.Panel>
      </Popover.Root>
    </div>
  );
}
```

## Props

### Popover.Root

| Name | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| children\* | `ReactNode` | - | - |
| defaultOpen | `boolean` | - | Whether the overlay is open by default (uncontrolled). |
| isOpen | `boolean` | - | Whether the overlay is open by default (controlled). |
| onOpenChange | `((isOpen: boolean) => void)` | - | Handler that is called when the overlay's open state changes. |

### Popover.Dialog

| Name | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| aria-describedby | `string` | - | Identifies the element (or elements) that describes the object. |
| aria-details | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| aria-label | `string` | - | Defines a string value that labels the current element. |
| aria-labelledby | `string` | - | Identifies the element (or elements) that labels the current element. |
| children | `((opts: DialogRenderProps) => ReactNode) \ | ReactNode` | - | Children of the dialog. A function may be provided to access a function to close the dialog. |
| className | `string` | `'react-aria-Dialog'` | The CSS \[className]\(https\://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. |
| dir | `string` | - | - |
| hidden | `boolean` | - | - |
| id | `string` | - | The element's unique identifier. See \[MDN]\(https\://developer.mozilla.org/en-US/docs/Web/HTML/Global\_attributes/id). |
| inert | `boolean` | - | - |
| isEntering | `boolean` | - | Whether the dialog is currently performing an entry animation. Focus is not moved into the dialog until the animation completes, since moving the screen reader cursor may cause scrolling that interrupts the animation. |
| lang | `string` | - | - |
| onAnimationEnd | `AnimationEventHandler<HTMLElement>` | - | - |
| onAnimationEndCapture | `AnimationEventHandler<HTMLElement>` | - | - |
| onAnimationIteration | `AnimationEventHandler<HTMLElement>` | - | - |
| onAnimationIterationCapture | `AnimationEventHandler<HTMLElement>` | - | - |
| onAnimationStart | `AnimationEventHandler<HTMLElement>` | - | - |
| onAnimationStartCapture | `AnimationEventHandler<HTMLElement>` | - | - |
| onAuxClick | `MouseEventHandler<HTMLElement>` | - | - |
| onAuxClickCapture | `MouseEventHandler<HTMLElement>` | - | - |
| onClick | `MouseEventHandler<HTMLElement>` | - | - |
| onClickCapture | `MouseEventHandler<HTMLElement>` | - | - |
| onContextMenu | `MouseEventHandler<HTMLElement>` | - | - |
| onContextMenuCapture | `MouseEventHandler<HTMLElement>` | - | - |
| onDoubleClick | `MouseEventHandler<HTMLElement>` | - | - |
| onDoubleClickCapture | `MouseEventHandler<HTMLElement>` | - | - |
| onGotPointerCapture | `PointerEventHandler<HTMLElement>` | - | - |
| onGotPointerCaptureCapture | `PointerEventHandler<HTMLElement>` | - | - |
| onLostPointerCapture | `PointerEventHandler<HTMLElement>` | - | - |
| onLostPointerCaptureCapture | `PointerEventHandler<HTMLElement>` | - | - |
| onMouseDown | `MouseEventHandler<HTMLElement>` | - | - |
| onMouseDownCapture | `MouseEventHandler<HTMLElement>` | - | - |
| onMouseEnter | `MouseEventHandler<HTMLElement>` | - | - |
| onMouseLeave | `MouseEventHandler<HTMLElement>` | - | - |
| onMouseMove | `MouseEventHandler<HTMLElement>` | - | - |
| onMouseMoveCapture | `MouseEventHandler<HTMLElement>` | - | - |
| onMouseOut | `MouseEventHandler<HTMLElement>` | - | - |
| onMouseOutCapture | `MouseEventHandler<HTMLElement>` | - | - |
| onMouseOver | `MouseEventHandler<HTMLElement>` | - | - |
| onMouseOverCapture | `MouseEventHandler<HTMLElement>` | - | - |
| onMouseUp | `MouseEventHandler<HTMLElement>` | - | - |
| onMouseUpCapture | `MouseEventHandler<HTMLElement>` | - | - |
| onPointerCancel | `PointerEventHandler<HTMLElement>` | - | - |
| onPointerCancelCapture | `PointerEventHandler<HTMLElement>` | - | - |
| onPointerDown | `PointerEventHandler<HTMLElement>` | - | - |
| onPointerDownCapture | `PointerEventHandler<HTMLElement>` | - | - |
| onPointerEnter | `PointerEventHandler<HTMLElement>` | - | - |
| onPointerLeave | `PointerEventHandler<HTMLElement>` | - | - |
| onPointerMove | `PointerEventHandler<HTMLElement>` | - | - |
| onPointerMoveCapture | `PointerEventHandler<HTMLElement>` | - | - |
| onPointerOut | `PointerEventHandler<HTMLElement>` | - | - |
| onPointerOutCapture | `PointerEventHandler<HTMLElement>` | - | - |
| onPointerOver | `PointerEventHandler<HTMLElement>` | - | - |
| onPointerOverCapture | `PointerEventHandler<HTMLElement>` | - | - |
| onPointerUp | `PointerEventHandler<HTMLElement>` | - | - |
| onPointerUpCapture | `PointerEventHandler<HTMLElement>` | - | - |
| onScroll | `UIEventHandler<HTMLElement>` | - | - |
| onScrollCapture | `UIEventHandler<HTMLElement>` | - | - |
| onTouchCancel | `TouchEventHandler<HTMLElement>` | - | - |
| onTouchCancelCapture | `TouchEventHandler<HTMLElement>` | - | - |
| onTouchEnd | `TouchEventHandler<HTMLElement>` | - | - |
| onTouchEndCapture | `TouchEventHandler<HTMLElement>` | - | - |
| onTouchMove | `TouchEventHandler<HTMLElement>` | - | - |
| onTouchMoveCapture | `TouchEventHandler<HTMLElement>` | - | - |
| onTouchStart | `TouchEventHandler<HTMLElement>` | - | - |
| onTouchStartCapture | `TouchEventHandler<HTMLElement>` | - | - |
| onTransitionCancel | `TransitionEventHandler<HTMLElement>` | - | - |
| onTransitionCancelCapture | `TransitionEventHandler<HTMLElement>` | - | - |
| onTransitionEnd | `TransitionEventHandler<HTMLElement>` | - | - |
| onTransitionEndCapture | `TransitionEventHandler<HTMLElement>` | - | - |
| onTransitionRun | `TransitionEventHandler<HTMLElement>` | - | - |
| onTransitionRunCapture | `TransitionEventHandler<HTMLElement>` | - | - |
| onTransitionStart | `TransitionEventHandler<HTMLElement>` | - | - |
| onTransitionStartCapture | `TransitionEventHandler<HTMLElement>` | - | - |
| onWheel | `WheelEventHandler<HTMLElement>` | - | - |
| onWheelCapture | `WheelEventHandler<HTMLElement>` | - | - |
| render | `DOMRenderFunction<"section", 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.&#xA;&#xA;Requirements:&#xA;&#xA;- You must render the expected element type (e.g. if \`\<button>\` is expected, you cannot render an \`\<a>\`).&#xA;- Only a single root DOM element can be rendered (no fragments).&#xA;- You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| role | `"alertdialog" \ | "dialog"` | `'dialog'` | The accessibility role for the dialog. |
| slot | `string \ | null` | - | 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. |
| style | `CSSProperties` | - | The inline \[style]\(https\://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. |
| suppressHydrationWarning | `boolean` | - | A React-only flag that suppresses the warning React normally logs when an element's server-rendered content doesn't match the client render during hydration. See \[React docs]\(https\://react.dev/reference/react-dom/client/hydrateRoot#suppressing-unavoidable-hydration-mismatch-errors). |
| translate | `"no" \ | "yes"` | - | - |

### Popover.HoverRoot

| Name | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| children\* | `ReactNode` | - | The trigger and Popover that make up the preview trigger. |
| closeDelay | `number` | `200` | The delay time in milliseconds before the preview closes. |
| defaultOpen | `boolean` | - | Whether the overlay is open by default (uncontrolled). |
| delay | `number` | `600` | The delay time in milliseconds before the preview opens. |
| isDisabled | `boolean` | - | Whether the tooltip should be disabled, independent from the trigger. |
| isOpen | `boolean` | - | Whether the overlay is open by default (controlled). |
| onOpenChange | `((isOpen: boolean) => void)` | - | Handler that is called when the overlay's open state changes. |

### Popover.Panel

| Name | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| children\* | `ReactNode` | - | The content rendered inside the popover. |
| placement | `Placements` | - | The placement of the element with respect to its anchor element. |
| aria-describedby | `string` | - | Identifies the element (or elements) that describes the object. |
| aria-details | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| aria-label | `string` | - | Defines a string value that labels the current element. |
| aria-labelledby | `string` | - | Identifies the element (or elements) that labels the current element. |
| arrowBoundaryOffset | `number` | `0` | The minimum distance the arrow's edge should be from the edge of the overlay element. |
| arrowRef | `RefObject<Element \ | null>` | - | A ref for the popover arrow element. |
| boundaryElement | `Element` | `document.body` | Element that that serves as the positioning boundary. |
| className | `ClassNameOrFunction<PopoverRenderProps>` | `'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. |
| containerPadding | `number` | `12` | The placement padding that should be applied between the element and its surrounding container. |
| crossOffset | `number` | `0` | The additional offset applied along the cross axis between the element and its anchor element. |
| defaultOpen | `boolean` | - | Whether the overlay is open by default (uncontrolled). |
| dir | `string` | - | - |
| getTargetRect | `((target: Element) => DOMRect \ | null)` | `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. |
| hidden | `boolean` | - | - |
| inert | `boolean` | - | - |
| isEntering | `boolean` | - | Whether the popover is currently performing an entry animation. |
| isExiting | `boolean` | - | Whether the popover is currently performing an exit animation. |
| isKeyboardDismissDisabled | `boolean` | `false` | Whether pressing the escape key to close the popover should be disabled.&#xA;&#xA;Most popovers should not use this option. When set to true, an alternative way to close the popover with a keyboard must be provided. |
| isNonModal | `boolean` | - | Whether the popover is non-modal, i.e. elements outside the popover may be interacted with by assistive technologies.&#xA;&#xA;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. |
| isOpen | `boolean` | - | Whether the overlay is open by default (controlled). |
| lang | `string` | - | - |
| maxHeight | `number` | - | The maxHeight specified for the overlay element. By default, it will take all space up to the current viewport height. |
| offset | `number` | `8` | The additional offset applied along the main axis between the element and its anchor element. |
| onAnimationEnd | `AnimationEventHandler<HTMLDivElement>` | - | - |
| onAnimationEndCapture | `AnimationEventHandler<HTMLDivElement>` | - | - |
| onAnimationIteration | `AnimationEventHandler<HTMLDivElement>` | - | - |
| onAnimationIterationCapture | `AnimationEventHandler<HTMLDivElement>` | - | - |
| onAnimationStart | `AnimationEventHandler<HTMLDivElement>` | - | - |
| onAnimationStartCapture | `AnimationEventHandler<HTMLDivElement>` | - | - |
| onAuxClick | `MouseEventHandler<HTMLDivElement>` | - | - |
| onAuxClickCapture | `MouseEventHandler<HTMLDivElement>` | - | - |
| onBlurWithin | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the target element and all descendants lose focus. |
| onClick | `MouseEventHandler<HTMLDivElement>` | - | - |
| onClickCapture | `MouseEventHandler<HTMLDivElement>` | - | - |
| onContextMenu | `MouseEventHandler<HTMLDivElement>` | - | - |
| onContextMenuCapture | `MouseEventHandler<HTMLDivElement>` | - | - |
| onDoubleClick | `MouseEventHandler<HTMLDivElement>` | - | - |
| onDoubleClickCapture | `MouseEventHandler<HTMLDivElement>` | - | - |
| onFocusWithin | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the target element or a descendant receives focus. |
| onFocusWithinChange | `((isFocusWithin: boolean) => void)` | - | Handler that is called when the the focus within state changes. |
| onGotPointerCapture | `PointerEventHandler<HTMLDivElement>` | - | - |
| onGotPointerCaptureCapture | `PointerEventHandler<HTMLDivElement>` | - | - |
| onLostPointerCapture | `PointerEventHandler<HTMLDivElement>` | - | - |
| onLostPointerCaptureCapture | `PointerEventHandler<HTMLDivElement>` | - | - |
| onMouseDown | `MouseEventHandler<HTMLDivElement>` | - | - |
| onMouseDownCapture | `MouseEventHandler<HTMLDivElement>` | - | - |
| onMouseEnter | `MouseEventHandler<HTMLDivElement>` | - | - |
| onMouseLeave | `MouseEventHandler<HTMLDivElement>` | - | - |
| onMouseMove | `MouseEventHandler<HTMLDivElement>` | - | - |
| onMouseMoveCapture | `MouseEventHandler<HTMLDivElement>` | - | - |
| onMouseOut | `MouseEventHandler<HTMLDivElement>` | - | - |
| onMouseOutCapture | `MouseEventHandler<HTMLDivElement>` | - | - |
| onMouseOver | `MouseEventHandler<HTMLDivElement>` | - | - |
| onMouseOverCapture | `MouseEventHandler<HTMLDivElement>` | - | - |
| onMouseUp | `MouseEventHandler<HTMLDivElement>` | - | - |
| onMouseUpCapture | `MouseEventHandler<HTMLDivElement>` | - | - |
| onOpenChange | `((isOpen: boolean) => void)` | - | Handler that is called when the overlay's open state changes. |
| onPointerCancel | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerCancelCapture | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerDown | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerDownCapture | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerEnter | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerLeave | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerMove | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerMoveCapture | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerOut | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerOutCapture | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerOver | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerOverCapture | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerUp | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerUpCapture | `PointerEventHandler<HTMLDivElement>` | - | - |
| onScroll | `UIEventHandler<HTMLDivElement>` | - | - |
| onScrollCapture | `UIEventHandler<HTMLDivElement>` | - | - |
| onTouchCancel | `TouchEventHandler<HTMLDivElement>` | - | - |
| onTouchCancelCapture | `TouchEventHandler<HTMLDivElement>` | - | - |
| onTouchEnd | `TouchEventHandler<HTMLDivElement>` | - | - |
| onTouchEndCapture | `TouchEventHandler<HTMLDivElement>` | - | - |
| onTouchMove | `TouchEventHandler<HTMLDivElement>` | - | - |
| onTouchMoveCapture | `TouchEventHandler<HTMLDivElement>` | - | - |
| onTouchStart | `TouchEventHandler<HTMLDivElement>` | - | - |
| onTouchStartCapture | `TouchEventHandler<HTMLDivElement>` | - | - |
| onTransitionCancel | `TransitionEventHandler<HTMLDivElement>` | - | - |
| onTransitionCancelCapture | `TransitionEventHandler<HTMLDivElement>` | - | - |
| onTransitionEnd | `TransitionEventHandler<HTMLDivElement>` | - | - |
| onTransitionEndCapture | `TransitionEventHandler<HTMLDivElement>` | - | - |
| onTransitionRun | `TransitionEventHandler<HTMLDivElement>` | - | - |
| onTransitionRunCapture | `TransitionEventHandler<HTMLDivElement>` | - | - |
| onTransitionStart | `TransitionEventHandler<HTMLDivElement>` | - | - |
| onTransitionStartCapture | `TransitionEventHandler<HTMLDivElement>` | - | - |
| onWheel | `WheelEventHandler<HTMLDivElement>` | - | - |
| onWheelCapture | `WheelEventHandler<HTMLDivElement>` | - | - |
| render | `DOMRenderFunction<"div", PopoverRenderProps>` | - | 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.&#xA;&#xA;Requirements:&#xA;&#xA;- You must render the expected element type (e.g. if \`\<button>\` is expected, you cannot render an \`\<a>\`).&#xA;- Only a single root DOM element can be rendered (no fragments).&#xA;- You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| scrollRef | `RefObject<Element \ | null>` | `overlayRef` | A ref for the scrollable region within the overlay. |
| shouldFlip | `boolean` | `true` | 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. |
| shouldSkipAnimation | `boolean` | - | Whether the popover should appear and disappear without an entry or exit animation. This is used by components such as PreviewTrigger to skip animations when quickly swapping between overlays. |
| shouldUpdatePosition | `boolean` | `true` | Whether the overlay should update its position automatically. |
| slot | `string \ | null` | - | 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. |
| style | `StyleOrFunction<PopoverRenderProps>` | - | 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. |
| suppressHydrationWarning | `boolean` | - | A React-only flag that suppresses the warning React normally logs when an element's server-rendered content doesn't match the client render during hydration. See \[React docs]\(https\://react.dev/reference/react-dom/client/hydrateRoot#suppressing-unavoidable-hydration-mismatch-errors). |
| translate | `"no" \ | "yes"` | - | - |
| trigger | `string` | - | 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. |
| triggerRef | `RefObject<Element \ | null>` | - | The ref for the element which the popover positions itself with respect to.&#xA;&#xA;When used within a trigger component such as DialogTrigger, MenuTrigger, Select, etc., this is set automatically. It is only required when used standalone. |

### Popover.Wrapper

| Name | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| children\* | `ReactNode` | - | The content rendered inside the popover. |
| placement | `Placements` | - | The placement of the element with respect to its anchor element. |
| aria-describedby | `string` | - | Identifies the element (or elements) that describes the object. |
| aria-details | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| aria-label | `string` | - | Defines a string value that labels the current element. |
| aria-labelledby | `string` | - | Identifies the element (or elements) that labels the current element. |
| arrowBoundaryOffset | `number` | `0` | The minimum distance the arrow's edge should be from the edge of the overlay element. |
| arrowRef | `RefObject<Element \ | null>` | - | A ref for the popover arrow element. |
| boundaryElement | `Element` | `document.body` | Element that that serves as the positioning boundary. |
| className | `ClassNameOrFunction<PopoverRenderProps>` | `'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. |
| containerPadding | `number` | `12` | The placement padding that should be applied between the element and its surrounding container. |
| crossOffset | `number` | `0` | The additional offset applied along the cross axis between the element and its anchor element. |
| defaultOpen | `boolean` | - | Whether the overlay is open by default (uncontrolled). |
| dir | `string` | - | - |
| getTargetRect | `((target: Element) => DOMRect \ | null)` | `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. |
| hidden | `boolean` | - | - |
| inert | `boolean` | - | - |
| isEntering | `boolean` | - | Whether the popover is currently performing an entry animation. |
| isExiting | `boolean` | - | Whether the popover is currently performing an exit animation. |
| isKeyboardDismissDisabled | `boolean` | `false` | Whether pressing the escape key to close the popover should be disabled.&#xA;&#xA;Most popovers should not use this option. When set to true, an alternative way to close the popover with a keyboard must be provided. |
| isNonModal | `boolean` | - | Whether the popover is non-modal, i.e. elements outside the popover may be interacted with by assistive technologies.&#xA;&#xA;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. |
| isOpen | `boolean` | - | Whether the overlay is open by default (controlled). |
| lang | `string` | - | - |
| maxHeight | `number` | - | The maxHeight specified for the overlay element. By default, it will take all space up to the current viewport height. |
| offset | `number` | `8` | The additional offset applied along the main axis between the element and its anchor element. |
| onAnimationEnd | `AnimationEventHandler<HTMLDivElement>` | - | - |
| onAnimationEndCapture | `AnimationEventHandler<HTMLDivElement>` | - | - |
| onAnimationIteration | `AnimationEventHandler<HTMLDivElement>` | - | - |
| onAnimationIterationCapture | `AnimationEventHandler<HTMLDivElement>` | - | - |
| onAnimationStart | `AnimationEventHandler<HTMLDivElement>` | - | - |
| onAnimationStartCapture | `AnimationEventHandler<HTMLDivElement>` | - | - |
| onAuxClick | `MouseEventHandler<HTMLDivElement>` | - | - |
| onAuxClickCapture | `MouseEventHandler<HTMLDivElement>` | - | - |
| onBlurWithin | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the target element and all descendants lose focus. |
| onClick | `MouseEventHandler<HTMLDivElement>` | - | - |
| onClickCapture | `MouseEventHandler<HTMLDivElement>` | - | - |
| onContextMenu | `MouseEventHandler<HTMLDivElement>` | - | - |
| onContextMenuCapture | `MouseEventHandler<HTMLDivElement>` | - | - |
| onDoubleClick | `MouseEventHandler<HTMLDivElement>` | - | - |
| onDoubleClickCapture | `MouseEventHandler<HTMLDivElement>` | - | - |
| onFocusWithin | `((e: FocusEvent<Element, Element>) => void)` | - | Handler that is called when the target element or a descendant receives focus. |
| onFocusWithinChange | `((isFocusWithin: boolean) => void)` | - | Handler that is called when the the focus within state changes. |
| onGotPointerCapture | `PointerEventHandler<HTMLDivElement>` | - | - |
| onGotPointerCaptureCapture | `PointerEventHandler<HTMLDivElement>` | - | - |
| onLostPointerCapture | `PointerEventHandler<HTMLDivElement>` | - | - |
| onLostPointerCaptureCapture | `PointerEventHandler<HTMLDivElement>` | - | - |
| onMouseDown | `MouseEventHandler<HTMLDivElement>` | - | - |
| onMouseDownCapture | `MouseEventHandler<HTMLDivElement>` | - | - |
| onMouseEnter | `MouseEventHandler<HTMLDivElement>` | - | - |
| onMouseLeave | `MouseEventHandler<HTMLDivElement>` | - | - |
| onMouseMove | `MouseEventHandler<HTMLDivElement>` | - | - |
| onMouseMoveCapture | `MouseEventHandler<HTMLDivElement>` | - | - |
| onMouseOut | `MouseEventHandler<HTMLDivElement>` | - | - |
| onMouseOutCapture | `MouseEventHandler<HTMLDivElement>` | - | - |
| onMouseOver | `MouseEventHandler<HTMLDivElement>` | - | - |
| onMouseOverCapture | `MouseEventHandler<HTMLDivElement>` | - | - |
| onMouseUp | `MouseEventHandler<HTMLDivElement>` | - | - |
| onMouseUpCapture | `MouseEventHandler<HTMLDivElement>` | - | - |
| onOpenChange | `((isOpen: boolean) => void)` | - | Handler that is called when the overlay's open state changes. |
| onPointerCancel | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerCancelCapture | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerDown | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerDownCapture | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerEnter | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerLeave | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerMove | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerMoveCapture | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerOut | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerOutCapture | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerOver | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerOverCapture | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerUp | `PointerEventHandler<HTMLDivElement>` | - | - |
| onPointerUpCapture | `PointerEventHandler<HTMLDivElement>` | - | - |
| onScroll | `UIEventHandler<HTMLDivElement>` | - | - |
| onScrollCapture | `UIEventHandler<HTMLDivElement>` | - | - |
| onTouchCancel | `TouchEventHandler<HTMLDivElement>` | - | - |
| onTouchCancelCapture | `TouchEventHandler<HTMLDivElement>` | - | - |
| onTouchEnd | `TouchEventHandler<HTMLDivElement>` | - | - |
| onTouchEndCapture | `TouchEventHandler<HTMLDivElement>` | - | - |
| onTouchMove | `TouchEventHandler<HTMLDivElement>` | - | - |
| onTouchMoveCapture | `TouchEventHandler<HTMLDivElement>` | - | - |
| onTouchStart | `TouchEventHandler<HTMLDivElement>` | - | - |
| onTouchStartCapture | `TouchEventHandler<HTMLDivElement>` | - | - |
| onTransitionCancel | `TransitionEventHandler<HTMLDivElement>` | - | - |
| onTransitionCancelCapture | `TransitionEventHandler<HTMLDivElement>` | - | - |
| onTransitionEnd | `TransitionEventHandler<HTMLDivElement>` | - | - |
| onTransitionEndCapture | `TransitionEventHandler<HTMLDivElement>` | - | - |
| onTransitionRun | `TransitionEventHandler<HTMLDivElement>` | - | - |
| onTransitionRunCapture | `TransitionEventHandler<HTMLDivElement>` | - | - |
| onTransitionStart | `TransitionEventHandler<HTMLDivElement>` | - | - |
| onTransitionStartCapture | `TransitionEventHandler<HTMLDivElement>` | - | - |
| onWheel | `WheelEventHandler<HTMLDivElement>` | - | - |
| onWheelCapture | `WheelEventHandler<HTMLDivElement>` | - | - |
| render | `DOMRenderFunction<"div", PopoverRenderProps>` | - | 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.&#xA;&#xA;Requirements:&#xA;&#xA;- You must render the expected element type (e.g. if \`\<button>\` is expected, you cannot render an \`\<a>\`).&#xA;- Only a single root DOM element can be rendered (no fragments).&#xA;- You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. |
| scrollRef | `RefObject<Element \ | null>` | `overlayRef` | A ref for the scrollable region within the overlay. |
| shouldFlip | `boolean` | `true` | 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. |
| shouldSkipAnimation | `boolean` | - | Whether the popover should appear and disappear without an entry or exit animation. This is used by components such as PreviewTrigger to skip animations when quickly swapping between overlays. |
| shouldUpdatePosition | `boolean` | `true` | Whether the overlay should update its position automatically. |
| slot | `string \ | null` | - | 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. |
| style | `StyleOrFunction<PopoverRenderProps>` | - | 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. |
| suppressHydrationWarning | `boolean` | - | A React-only flag that suppresses the warning React normally logs when an element's server-rendered content doesn't match the client render during hydration. See \[React docs]\(https\://react.dev/reference/react-dom/client/hydrateRoot#suppressing-unavoidable-hydration-mismatch-errors). |
| translate | `"no" \ | "yes"` | - | - |
| trigger | `string` | - | 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. |
| triggerRef | `RefObject<Element \ | null>` | - | The ref for the element which the popover positions itself with respect to.&#xA;&#xA;When used within a trigger component such as DialogTrigger, MenuTrigger, Select, etc., this is set automatically. It is only required when used standalone. |