React Aria
DocsReleasesBlog
React Aria

Popover

A popover is an overlay element positioned relative to a trigger.

Theme 
placement 
 
 
shouldFlip 
Example
Popover.tsx
Popover.css
import {DialogTrigger} from 'react-aria-components';
import {Popover} from './Popover';
import {Button} from './Button';
import {Switch} from './Switch';
import {Settings2} from 'lucide-react';

function Example(props) {
  return (
    <DialogTrigger>
      <Button aria-label="Settings">
        <Settings2 size={20} />
      </Button>
      <Popover {...props}>
        <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>
          <Switch defaultSelected>Wi-Fi</Switch>
          <Switch defaultSelected>Bluetooth</Switch>
          <Switch>Mute</Switch>
        </div>
      </Popover>
    </DialogTrigger>
  );
}

Custom trigger

DialogTrigger works with any pressable React Aria component (e.g. Button, Link, etc.). Use the <Pressable> component or usePress hook to wrap a custom trigger element such as a third party component or DOM element.

import {Pressable, DialogTrigger} from 'react-aria-components';
import {Popover} from './Popover';

<DialogTrigger>
  <Pressable>
    <span role="button">Custom trigger</span>
  </Pressable>
  <Popover style={{padding: 16}}>
    This popover was triggered by a custom button.
  </Popover>
</DialogTrigger>

const CustomTrigger = React.forwardRef((props, ref) => (
  <button {...props} ref={ref} />
));

Custom anchor

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

Popover will be positioned relative to me
import {useState, useRef} from 'react';
import {Popover} from './Popover';
import {Button} from './Button';

function Example() {
  let [isOpen, setOpen] = useState(false);
  let triggerRef = useRef(null);

  return (
    <div>
      <Button onPress={() => setOpen(true)}>Trigger</Button>
      <span ref={triggerRef} style={{paddingLeft: 12}}>Popover will be positioned relative to me</span>
      <Popover
        style={{padding: 16}}
        triggerRef={triggerRef}
        isOpen={isOpen}
        onOpenChange={setOpen}>
        I'm over here!
      </Popover>
    </div>
  );
}

Examples

API

Arrow (optional)Popover 
<DialogTrigger>
  <Button />
  <Popover>
    <OverlayArrow />
  </Popover>
</DialogTrigger>

DialogTrigger

A DialogTrigger opens a dialog when a trigger element is pressed.

NameType
childrenReactNode

Popover

A popover is an overlay element positioned relative to a trigger.

NameTypeDefault
triggerstringDefault: —
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<Element | null>Default: —
The ref for the element which the popover positions itself with respect to. When used within a trigger component such as DialogTrigger, MenuTrigger, Select, etc., this is set automatically. It is only required when used standalone.
isEnteringbooleanDefault: —
Whether the popover is currently performing an entry animation.
isExitingbooleanDefault: —
Whether the popover is currently performing an exit animation.
placementDefault: 'bottom'
The placement of the element with respect to its anchor element.
arrowRef<Element | null>Default: —
A ref for the popover arrow element.
isNonModalbooleanDefault: —
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.
isKeyboardDismissDisabledbooleanDefault: 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) => booleanDefault: —
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.
boundaryElementElementDefault: document.body
Element that that serves as the positioning boundary.
scrollRef<Element | null>Default: overlayRef
A ref for the scrollable region within the overlay.
shouldUpdatePositionbooleanDefault: true
Whether the overlay should update its position automatically.
maxHeightnumberDefault: —
The maxHeight specified for the overlay element. By default, it will take all space up to the current viewport height.
arrowBoundaryOffsetnumberDefault: 0
The minimum distance the arrow's edge should be from the edge of the overlay element.
children<>Default: —
The children of the component. A function may be provided to alter the children based on component state.

Default className: react-aria-Popover

Render PropCSS Selector
triggerCSS Selector: [data-trigger="..."]
The name of the component that triggered the popover, e.g. "DialogTrigger" or "ComboBox".
placementCSS Selector: [data-placement="left | right | top | bottom"]
The placement of the popover relative to the trigger.
isEnteringCSS Selector: [data-entering]
Whether the popover is currently entering. Use this to apply animations.
isExitingCSS Selector: [data-exiting]
Whether the popover is currently exiting. Use this to apply animations.
CSS Variable
--trigger-width
The width of the popover trigger element.
--trigger-anchor-point
The position of the trigger relative to the popover. Use with transform-origin when applying scale transitions.

OverlayArrow

An OverlayArrow renders a custom arrow element relative to an overlay element such as a popover or tooltip such that it aligns with a trigger element.

NameType
children<>
The children of the component. A function may be provided to alter the children based on component state.

Default className: react-aria-OverlayArrow

Render PropCSS Selector
placementCSS Selector: [data-placement="left | right | top | bottom"]
The placement of the overlay relative to the trigger.

Related pages