Popover

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.

boolean

The controlled open state of the popover. Must be used in conjunction with onOpenChange.

boolean

The open state of the popover when it is initially rendered. Use when you do not need to control its open state.

(open: boolean) => void

Event handler called when the open state of the popover changes.

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.

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.

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.

HTMLElement

default:"document.body"

Specify a container element to portal the content into.

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.

boolean

default:"false"

Change the default rendered element for the one passed as a child, merging their props and behavior.

'top' | 'right' | 'bottom' | 'left'

default:"'bottom'"

The preferred side of the trigger to render against when open.

number

default:"0"

The distance in pixels from the trigger.

'start' | 'center' | 'end'

default:"'center'"

The preferred alignment against the trigger. May change when collisions occur.

number

default:"0"

An offset in pixels from the “start” or “end” alignment options.

boolean

default:"true"

When true, overrides the side and align preferences to prevent collisions with boundary edges.

Element | Element[]

default:"[]"

The element used as the collision boundary. By default this is the viewport.

number | Padding

default:"0"

The distance in pixels from the boundary edges where collision detection should occur.

'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.

boolean

default:"false"

Whether to hide the content when the trigger becomes fully occluded.

(event: Event) => void

Event handler called when focus moves into the component after opening. It can be prevented by calling event.preventDefault.

(event: Event) => void

Event handler called when focus moves to the trigger after closing. It can be prevented by calling event.preventDefault.

(event: KeyboardEvent) => void

Event handler called when the escape key is down. It can be prevented by calling event.preventDefault.

(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.

(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.

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.

boolean

default:"false"

Change the default rendered element for the one passed as a child, merging their props and behavior.

number

default:"10"

The width of the arrow in pixels.

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>
  );
}

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

function PositionedPopover() {
  return (
    <Popover.Root>
      <Popover.Trigger>Show Info</Popover.Trigger>
      <Popover.Portal>
        <Popover.Content
          side="top"
          align="start"
          sideOffset={5}
          className="popover-content"
        >
          <p>This popover appears above and starts at the left.</p>
          <Popover.Arrow />
        </Popover.Content>
      </Popover.Portal>
    </Popover.Root>
  );
}

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

function ControlledPopover() {
  const [open, setOpen] = useState(false);

  return (
    <Popover.Root open={open} onOpenChange={setOpen}>
      <Popover.Trigger>Settings</Popover.Trigger>
      <Popover.Portal>
        <Popover.Content>
          <div>
            <label>
              <input type="checkbox" />
              Enable notifications
            </label>
            <label>
              <input type="checkbox" />
              Auto-save
            </label>
          </div>
          <button onClick={() => setOpen(false)}>Done</button>
        </Popover.Content>
      </Popover.Portal>
    </Popover.Root>
  );
}

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

function AnchoredPopover() {
  return (
    <Popover.Root>
      <Popover.Trigger>Open</Popover.Trigger>
      <Popover.Anchor asChild>
        <div className="custom-anchor">
          Popover will position relative to this element
        </div>
      </Popover.Anchor>
      <Popover.Portal>
        <Popover.Content>
          <p>Anchored to the div above, not the trigger.</p>
        </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

Overlays

Navigation

Forms

Layout

Data Display

Utilities

Overview

Features

Installation

Anatomy

API Reference

Root

Trigger

Anchor

Portal

Content

Close

Arrow

Example

Accessibility

Keyboard Interactions

​Overview

​Features

​Installation

​Anatomy

​API Reference

​Root

​Trigger

​Anchor

​Portal

​Content

​Close

​Arrow

​Example

​Accessibility

​Keyboard Interactions

Overview

Features

Installation

Anatomy

API Reference

Root

Trigger

Anchor

Portal

Content

Close

Arrow

Example

Accessibility

Keyboard Interactions