Popover

Overview

Popover displays floating content anchored to a trigger element. It includes smart positioning with collision detection, automatic focus management, and keyboard navigation.

Basic usage

import { Popover } from '@raystack/apsara';

<Popover>
  <Popover.Trigger asChild>
    <button>Open popover</button>
  </Popover.Trigger>
  
  <Popover.Content>
    <div>Popover content</div>
  </Popover.Content>
</Popover>

Components

The root component that manages popover state and positioning context.

boolean

Controls the open state of the popover (controlled mode).

boolean

The initial open state in uncontrolled mode.

(open: boolean) => void

Callback fired when the open state changes.

Whether the popover is modal (blocks interaction with content behind it).

boolean

Whether to open the popover on hover instead of click.

Popover.Trigger

A button that opens the popover when activated.

boolean

When true, merges props with the immediate child element instead of rendering a button.

The popover content container with positioning logic.

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

default:"'bottom'"

The preferred side of the trigger to render the popover.

'start' | 'center' | 'end'

default:"'center'"

The preferred alignment against the trigger.

number

default:"4"

The distance in pixels from the trigger.

number

The offset in pixels from the aligned edge.

number

default:"3"

The padding in pixels from the viewport edges for collision detection.

'partial' | 'always'

The sticky behavior of the popover during scrolling.

boolean

Whether to hide the popover when the trigger is fully occluded.

number | React.RefObject

The element that receives focus when the popover opens.

React.RefObject

The element that receives focus when the popover closes.

string

Additional CSS classes for the popover content.

A button that closes the popover when clicked.

boolean

When true, merges props with the immediate child element instead of rendering a button.

Usage examples

<Popover>
  <Popover.Trigger asChild>
    <button>Open above</button>
  </Popover.Trigger>
  
  <Popover.Content side="top" align="start">
    <div>This popover appears above the trigger, aligned to the start.</div>
  </Popover.Content>
</Popover>

With custom offset

<Popover>
  <Popover.Trigger asChild>
    <button>Open popover</button>
  </Popover.Trigger>
  
  <Popover.Content sideOffset={12} alignOffset={8}>
    <div>Popover with custom offset values.</div>
  </Popover.Content>
</Popover>

Hover trigger

<Popover openOnHover>
  <Popover.Trigger asChild>
    <button>Hover me</button>
  </Popover.Trigger>
  
  <Popover.Content>
    <div>Opens on hover instead of click.</div>
  </Popover.Content>
</Popover>

function ControlledPopover() {
  const [open, setOpen] = useState(false);
  
  return (
    <Popover open={open} onOpenChange={setOpen}>
      <Popover.Trigger asChild>
        <button>Toggle popover</button>
      </Popover.Trigger>
      
      <Popover.Content>
        <div>
          <p>Controlled popover content</p>
          <button onClick={() => setOpen(false)}>Close</button>
        </div>
      </Popover.Content>
    </Popover>
  );
}

With close button

<Popover>
  <Popover.Trigger asChild>
    <button>Open popover</button>
  </Popover.Trigger>
  
  <Popover.Content>
    <div>
      <h3>Popover title</h3>
      <p>Some content here.</p>
      <Popover.Close asChild>
        <button>Close</button>
      </Popover.Close>
    </div>
  </Popover.Content>
</Popover>

<Popover modal>
  <Popover.Trigger asChild>
    <button>Open modal popover</button>
  </Popover.Trigger>
  
  <Popover.Content>
    <div>This popover blocks interaction with content behind it.</div>
  </Popover.Content>
</Popover>

Positioning

The Popover uses smart positioning logic:

Preferred side: Set via the side prop
Collision detection: Automatically flips to the opposite side if there isn’t enough space
Alignment: Control via the align prop (start, center, end)
Offsets: Fine-tune position with sideOffset and alignOffset

All positioning is handled automatically with viewport boundary detection:

<Popover.Content
  side="bottom"
  align="start"
  sideOffset={8}
  collisionPadding={10}
/>

Accessibility features

Keyboard navigation: Arrow keys to navigate, Enter/Space to activate
ESC to close: Press Escape to close the popover
Focus management: Automatic focus handling with initialFocus and finalFocus props
Focus return: Focus returns to the trigger when closed
ARIA attributes: Proper ARIA relationships between trigger and content
Screen reader support: Announces popover state changes

Trigger patterns

The Popover.Trigger component supports two usage patterns:

Default button: Renders a button when no children provided or asChild is false
Custom trigger: Use asChild to merge popover functionality with your component

{/* Default button */}
<Popover.Trigger>Open</Popover.Trigger>

{/* Custom trigger */}
<Popover.Trigger asChild>
  <button className="custom-button">Open</button>
</Popover.Trigger>

Get Started

Guides

Layout Components

Navigation Components

Data Display

Form Components

Feedback Components

Overlay Components

Utility Components

Overview

Basic usage

Components

Popover (Root)

Popover.Trigger

Popover.Content

Popover.Close

Usage examples

Positioned popover

With custom offset

Hover trigger

Controlled popover

With close button

Positioning

Accessibility features

Trigger patterns

​Overview

​Basic usage

​Components

​Popover (Root)

​Popover.Trigger

​Popover.Content

​Popover.Close

​Usage examples

​Positioned popover

​With custom offset

​Hover trigger

​Controlled popover

​With close button

​Modal popover

​Positioning

​Accessibility features

​Trigger patterns

Overview

Basic usage

Components

Popover (Root)

Popover.Trigger

Popover.Content

Popover.Close

Usage examples

Positioned popover

With custom offset

Hover trigger

Controlled popover

With close button

Modal popover

Positioning

Accessibility features

Trigger patterns