Popover·component·@astryxdesign/core

Popover

A click-triggered overlay anchored to a button or trigger element. Use it for secondary actions, inline confirmations, or supplementary information that does not warrant a full dialog. For hover previews use HoverCard, for brief helper text use Tooltip.

Open in Playground @astryxdesign/core/Popover

Showcases and examples

6 documented examples

Popover

Popover API entry

Open Playground ↗

Preview loads on approachPreview loads on approach

Exact source · popover-showcase

// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

import {useState} from 'react';
import {Popover} from '@astryxdesign/core/Popover';
import {Button} from '@astryxdesign/core/Button';
import {VStack} from '@astryxdesign/core/Layout';
import {Text, Heading} from '@astryxdesign/core/Text';
import {Divider} from '@astryxdesign/core/Divider';

export default function PopoverShowcase() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <Popover
      isOpen={isOpen}
      onOpenChange={setIsOpen}
      hasAutoFocus={false}
      placement="below"
      label="Settings"
      width={280}
      content={
        <VStack gap={3}>
          <Heading level={4} tabIndex={0}>
            Settings
          </Heading>
          <Divider />
          <Text type="body">
            Notifications, dark mode, and sound preferences.
          </Text>
        </VStack>
      }>
      <Button label="Settings">Settings</Button>
    </Popover>
  );
}

Usage

Keep popover content focused on a single task or piece of information.
Provide a clear way to close: either by clicking outside or with an explicit close button.
Theme the painted surface through popover. Existing popover-surface overrides remain supported for compatibility, while new themes use the canonical target.
Nest popovers inside other popovers; it creates confusing focus and navigation.
Assume input complexity alone determines the presentation; evaluate the task's focus, space, and interaction requirements.
Assume scrolling alone means Popover is the wrong component; a bounded Popover may scroll while a focused anchored interaction remains appropriate.

Typed props

Prop	Type and behavior
`children`	`ReactNode` Trigger element. Must contain a <button> or [role="button"] element.
`anchorRef`	`React.RefObject<HTMLElement>` External ref to use as the popover anchor in sibling mode.
`content`	`ReactNode` · required Content to display inside the popover. Slot: Text
`placement`	`'above' \| 'below' \| 'start' \| 'end'` · default 'below' Position placement relative to the trigger. Logical: start/end resolve against the popover's own inherited direction, so RTL contexts mirror automatically in pure CSS.
`alignment`	`'start' \| 'center' \| 'end'` · default 'start' Alignment along the placement axis. Logical: start/end follow the popover's own inherited direction (RTL mirrors).
`isOpen`	`boolean` Whether the popover is shown in controlled mode.
`onOpenChange`	`(isOpen: boolean) => void` Callback fired when the popover visibility changes.
`isEnabled`	`boolean` · default true When false, trigger interactions are ignored.
`width`	`number \| string` · default 'auto' Width of the popover container. The layer still caps to the viewport with alignment-aware safe-area gutters before scrolling long content.
`label`	`string` Accessible label for the popover dialog.
`role`	`'dialog' \| 'none'` · default 'dialog' ARIA role for the popover wrapper. Use dialog for dialog-style popovers; use none when content provides its own role, like menu or listbox.
`isModal`	`boolean` · default true Whether a dialog-style popover sets aria-modal. Only applies when role is dialog.
`hasCloseButton`	`boolean` · default true Whether to include a hidden close button for accessibility.
`closeButtonLabel`	`string` · default 'Close popover' Label for the hidden close button.
`hasAutoFocus`	`boolean` · default true Whether to move focus into the popover when it opens. Focus enters the first genuine content control; dialogs with none fall back to the labeled surface. The generated fallback close control stays hidden until reached through keyboard navigation. Set to false for input-owned focus, inline showcases, or documentation previews.
`hasLightDismiss`	`boolean` · default true Whether clicking outside dismisses the popover. Set to false for surfaces that stay open until explicitly dismissed, like onboarding coachmarks.
`hasEscapeDismiss`	`boolean` · default true Whether pressing Escape dismisses the popover. Only takes full effect together with hasLightDismiss={false}, since native light dismiss also closes on Escape.
`xstyle`	`StyleXStyles` StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.

Anatomy

Trigger element · required

Caller-supplied or externally referenced control that anchors and toggles the popover.

Popover surface · required

Painted surface owned by Popover. Theme it through the canonical popover target; popover-surface remains supported as a deprecated compatibility alias.

Popover content · required

Caller-supplied content rendered inside the surface.

Fallback close control · optional

Keyboard-reachable close affordance appended by usePopover when enabled.

Theming

Targets

astryx-popover

astryx-popover-surface

Deprecated; use popover.

Variables

--_popover-radius · private

Border radius of the popover surface

Default: var(--radius-container)

Derived properties

borderRadius

Uses --_popover-radius.