Skip to main content

​
Overview

A popover is a floating container that displays rich content anchored to a trigger element.

​
Features

  • Can be controlled or uncontrolled
  • Customize side, alignment, offsets, collision handling
  • Optionally render in a Portal
  • Focus management and restoration
  • Supports modal or non-modal mode
  • Esc key closes the popover
  • Clicking outside closes the popover

​
Installation

npm install @radix-ui/react-popover

​
Anatomy

Import all parts and piece them together. 
import * as Popover from '@radix-ui/react-popover';

export default () => (
  <Popover.Root>
    <Popover.Trigger />
    <Popover.Anchor />
    <Popover.Portal>
      <Popover.Content>
        <Popover.Close />
        <Popover.Arrow />
      </Popover.Content>
    </Popover.Portal>
  </Popover.Root>
);

​
API Reference

​
Root

Contains all the parts of a popover.
​
open
boolean
The controlled open state of the popover. Must be used in conjunction with onOpenChange.
​
defaultOpen
boolean
The open state of the popover when it is initially rendered. Use when you do not need to control its open state.
​
onOpenChange
(open: boolean) => void
Event handler called when the open state of the popover changes.
​
modal
boolean
default:"false"
The modality of the popover. When set to true, interaction with outside elements will be disabled and only popover content will be visible to screen readers.

​
Trigger

The button that toggles the popover.
​
asChild
boolean
default:"false"
Change the default rendered element for the one passed as a child, merging their props and behavior.
Supports all standard HTML button attributes.

​
Anchor

An optional element to position the popover against. If not set, will position against the trigger.
​
asChild
boolean
default:"false"
Change the default rendered element for the one passed as a child, merging their props and behavior.

​
Portal

When used, portals the content part into the body.
​
container
HTMLElement
default:"document.body"
Specify a container element to portal the content into.
​
forceMount
boolean
Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.

​
Content

The component that pops out when the popover is open.
​
asChild
boolean
default:"false"
Change the default rendered element for the one passed as a child, merging their props and behavior.
​
side
'top' | 'right' | 'bottom' | 'left'
default:"'bottom'"
The preferred side of the trigger to render against when open.
​
sideOffset
number
default:"0"
The distance in pixels from the trigger.
​
align
'start' | 'center' | 'end'
default:"'center'"
The preferred alignment against the trigger. May change when collisions occur.
​
alignOffset
number
default:"0"
An offset in pixels from the “start” or “end” alignment options.
​
avoidCollisions
boolean
default:"true"
When true, overrides the side and align preferences to prevent collisions with boundary edges.
​
collisionBoundary
Element | Element[]
default:"[]"
The element used as the collision boundary. By default this is the viewport.
​
collisionPadding
number | Padding
default:"0"
The distance in pixels from the boundary edges where collision detection should occur.
​
sticky
'partial' | 'always'
default:"'partial'"
The sticky behavior on the align axis. partial will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst always will keep the content in the boundary regardless.
​
hideWhenDetached
boolean
default:"false"
Whether to hide the content when the trigger becomes fully occluded.
​
onOpenAutoFocus
(event: Event) => void
Event handler called when focus moves into the component after opening. It can be prevented by calling event.preventDefault.
​
onCloseAutoFocus
(event: Event) => void
Event handler called when focus moves to the trigger after closing. It can be prevented by calling event.preventDefault.
​
onEscapeKeyDown
(event: KeyboardEvent) => void
Event handler called when the escape key is down. It can be prevented by calling event.preventDefault.
​
onPointerDownOutside
(event: PointerDownOutsideEvent) => void
Event handler called when a pointer event occurs outside the bounds of the component. It can be prevented by calling event.preventDefault.
​
onInteractOutside
(event: PointerDownOutsideEvent | FocusOutsideEvent) => void
Event handler called when an interaction happens outside the bounds of the component. It can be prevented by calling event.preventDefault.

​
Close

The button that closes the popover.
​
asChild
boolean
default:"false"
Change the default rendered element for the one passed as a child, merging their props and behavior.

​
Arrow

An optional arrow element to render alongside the popover.
​
asChild
boolean
default:"false"
Change the default rendered element for the one passed as a child, merging their props and behavior.
​
width
number
default:"10"
The width of the arrow in pixels.
​
height
number
default:"5"
The height of the arrow in pixels.

​
Example

import * as Popover from '@radix-ui/react-popover';

function PopoverDemo() {
  return (
    <Popover.Root>
      <Popover.Trigger>Open Popover</Popover.Trigger>
      <Popover.Portal>
        <Popover.Content className="popover-content">
          <div>
            <h3>Dimensions</h3>
            <p>Width: 100%</p>
            <p>Height: auto</p>
          </div>
          <Popover.Close>Close</Popover.Close>
          <Popover.Arrow className="popover-arrow" />
        </Popover.Content>
      </Popover.Portal>
    </Popover.Root>
  );
}

​
Accessibility

Closes when the user presses the Esc key or interacts outside of the popover.

​
Keyboard Interactions

  • Space - Opens/closes the popover
  • Enter - Opens/closes the popover
  • Tab - Moves focus to the next focusable element
  • Shift + Tab - Moves focus to the previous focusable element
  • Esc - Closes the popover and moves focus to trigger

Build docs developers (and LLMs) love

Get started for freeTalk to us