Popover

Displays rich content in a portal, triggered by a button.

Features

Can be controlled or uncontrolled.
Customise side, alignment, offsets, collision handling.
Optionally render a pointing arrow.
Focus is fully managed and customizable.
Dismissing and layering behavior is highly customizable.

Installation

Install the component from your command line.

npm install @radix-ui/react-popover

npm install @radix-ui/react-popover

Anatomy

Import the components and piece the parts together.

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

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

import * as Popover from '@radix-ui/react-popover';
export default () => (
  <Popover.Root>
    <Popover.Trigger />
    <Popover.Content>
      <Popover.Close />
      <Popover.Arrow />
    </Popover.Content>
  </Popover.Root>
);

Basic example

Create your styled popover component from the primitive parts.

// import { styled } from 'path-to/stitches.config';
import * as Popover from '@radix-ui/react-popover';

const StyledContent = styled(Popover.Content, {
  borderRadius: 3,
  padding: '20px',
  fontSize: 14,
  backgroundColor: 'gainsboro',
  color: 'black',
});

const StyledArrow = styled(Popover.Arrow, {
  fill: 'gainsboro',
});

export default () => (
  <Popover.Root>
    <Popover.Trigger>Trigger</Popover.Trigger>
    <StyledContent>
      <h3>Popover content</h3>
      <p>Are you sure you wanna do this?</p>
      <Popover.Close>Yes</Popover.Close>
      <StyledArrow />
    </StyledContent>
  </Popover.Root>
);

// import { styled } from 'path-to/stitches.config';
import * as Popover from '@radix-ui/react-popover';
const StyledContent = styled(Popover.Content, {
  borderRadius: 3,
  padding: '20px',
  fontSize: 14,
  backgroundColor: 'gainsboro',
  color: 'black',
});
const StyledArrow = styled(Popover.Arrow, {
  fill: 'gainsboro',
});
export default () => (
  <Popover.Root>
    <Popover.Trigger>Trigger</Popover.Trigger>
    <StyledContent>
      <h3>Popover content</h3>
      <p>Are you sure you wanna do this?</p>
      <Popover.Close>Yes</Popover.Close>
      <StyledArrow />
    </StyledContent>
  </Popover.Root>
);

API Reference

Root

Contains all the parts of a popover.

Prop	Type	Default	Required
`defaultOpen`	`boolean`
`open`	`boolean`
`onOpenChange`	`function`

Trigger

The button that toggles the popover. By default, the Popover.Content will position itself against the trigger.

Prop	Type	Default	Required
`as`	`enum`	`button`

Content

The component that pops out when the popover is open.

Prop	Type	Default
`as`	`enum`	`div`
`trapFocus`	`boolean`	`true`
`onOpenAutoFocus`	`function`
`onCloseAutoFocus`	`function`
`disableOutsidePointerEvents`	`boolean`	`false`
`onEscapeKeyDown`	`function`
`onPointerDownOutside`	`function`
`onFocusOutside`	`function`
`onInteractOutside`	`function`
`disableOutsideScroll`	`boolean`	`false`
`portalled`	`boolean`	`true`
`forceMount`	`boolean`
`anchorRef`	`ref`
`side`	`enum`	`"bottom"`
`sideOffset`	`number`	`0`
`align`	`enum`	`"center"`
`alignOffset`	`number`	`0`
`avoidCollisions`	`boolean`	`true`
`collisionTolerance`	`boolean`	`0`

Arrow

An optional arrow element to render alongside the popover. This can be used to help visually link the anchor with the Popover.Content. Must be rendered inside Popover.Content.

Prop	Type	Default
`as`	`enum`	`svg`
`width`	`number`	`10`
`height`	`number`	`5`
`offset`	`number`

Close

The button that closes an open popover.

Prop	Type	Default	Required
`as`	`enum`	`button`

We expose a CSS custom property --radix-popover-content-transform-origin. Use it to animate the content from its computed origin based on side, sideOffset, align, alignOffset and any collisions.

const scaleIn = css.keyframes({
  '0%': { opacity: 0, transform: 'scale(0)' },
  '100%': { opacity: 1, transform: 'scale(1)' },
});

const StyledContent = styled(Popover.Content, {
  transformOrigin: 'var(--radix-popover-content-transform-origin)',
  animation: `${scaleIn} 0.5s ease-out`,
});

const scaleIn = css.keyframes({
  '0%': { opacity: 0, transform: 'scale(0)' },
  '100%': { opacity: 1, transform: 'scale(1)' },
});
const StyledContent = styled(Popover.Content, {
  transformOrigin: 'var(--radix-popover-content-transform-origin)',
  animation: `${scaleIn} 0.5s ease-out`,
});

Collision-aware animations

We expose data-side and data-align attributes. Their values will change at runtime to reflect collisions. Use them to create collision and direction-aware animations.

const slideDown = css.keyframes({
  '0%': { opacity: 0, transform: 'translateY(-10px)' },
  '100%': { opacity: 1, transform: 'translateY(0)' },
});

const slideUp = css.keyframes({
  '0%': { opacity: 0, transform: 'translateY(10px)' },
  '100%': { opacity: 1, transform: 'translateY(0)' },
});

const StyledContent = styled(Popover.Content, {
  '&[data-side="top"]': { animationName: slideUp },
  '&[data-side="bottom"]': { animationName: slideDown },
  animationDuration: '0.6s',
  animationTimingFunction: 'cubic-bezier(0.16, 1, 0.3, 1)',
});

const slideDown = css.keyframes({
  '0%': { opacity: 0, transform: 'translateY(-10px)' },
  '100%': { opacity: 1, transform: 'translateY(0)' },
});
const slideUp = css.keyframes({
  '0%': { opacity: 0, transform: 'translateY(10px)' },
  '100%': { opacity: 1, transform: 'translateY(0)' },
});
const StyledContent = styled(Popover.Content, {
  '&[data-side="top"]': { animationName: slideUp },
  '&[data-side="bottom"]': { animationName: slideDown },
  animationDuration: '0.6s',
  animationTimingFunction: 'cubic-bezier(0.16, 1, 0.3, 1)',
});

Accessibility

Adheres to the Dialog WAI-ARIA design pattern.

Keyboard Interactions

Key	Description
`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 `Popover.Trigger`.