Popover

Non-modal anchored surface on the shared overlay runtime with flip/shift/collision and safe-area policy.

Distribution status

BeeUI 0.86.2-rc.3 is public on npm under the opt-in next dist-tag (observed 2026-09-25T06:25:18.371Z). latest currently resolves to 0.86.2-rc.3 and lags next until the owner moves it for all four packages. See Start for the full install commands. The import shape below works against the published package; the repository-local Registry command remains available as a no-registry-required alternative from a BeeUI checkout. Pin @0.86.2-rc.3 instead of @next for an immutable version in CI.

Identity

• Category: Overlays & feedback
• Status: stable public Registry/export-map component family
• Targets: iOS · Android · Web, subject to the compatibility contract
• Prerequisites: @beemvp/beeui-ui installed (or this component’s source copied via the Registry CLI below) and, on Web, the BeeUI Tailwind/Uniwind theme CSS loaded — see Start for full platform setup.
• Source: packages/ui/src/components/popover.tsx

Import

import { Popover, PopoverClose, PopoverContent, PopoverDescription, PopoverTitle, PopoverTrigger } from '@beemvp/beeui-ui';

There is no documented deep/private source import. For source ownership from a BeeUI checkout:

pnpm beeui add popover

Registry (used throughout this page) is BeeUI’s source-ownership manifest — registry/registry.json — that the pnpm beeui/@beemvp/beeui-cli CLI reads to copy a component’s real source into your app and rewrite its internal imports; it is not an npm package index. This component’s own Registry entry: registry/registry.json.

Composition and public API

• Family exports: Popover PopoverClose PopoverContent PopoverDescription PopoverTitle PopoverTrigger
  • Also routed here, outside the Registry family:
    • popover
  • Package export subpath: @beemvp/beeui-ui/popover

Exported types: PopoverAlign, PopoverCloseProps, PopoverCollisionPadding, PopoverContentProps, PopoverDescriptionProps, PopoverDirection, PopoverPlacement, PopoverProps, PopoverTitleProps, PopoverTriggerProps

The generated API inventory is mechanically joined to packages/ui/src/index.ts, Registry metadata, and the component reference contract. Each type’s field table below is parsed directly from that source, not a second hand-maintained copy; for the fuller behavior narrative see the canonical component behavior catalog.

State and behavior contract

Controlled (open+onOpenChange) or uncontrolled (defaultOpen) non-modal anchored surface reusing the shared BeeUIProvider overlay runtime; among nested overlays, only the topmost open popover dismisses on an outside press or Escape.

Props

PopoverCloseProps

PopoverCloseProps is exactly ButtonProps.

Prop	Type	Default	Description
children	React.ReactNode	—	Content rendered inside this element. The family’s composition section states which children it expects.
className	string	—	Extra utility classes, merged after the component’s own via cn(...), so they win on conflict. An escape hatch for source-owned and application work, not a cross-engine portability guarantee.
labelClassName	string	—	Extra utility classes for the label text specifically, merged after the component’s own.
loading	boolean	false	Shows a spinner in place of the label, sets aria-busy, and disables presses. Defaults to false.
size	'sm' | 'md' | 'lg' | 'icon'	'md'	Chooses this element’s size from buttonVariants’s presets, declared in packages/ui/src/components/button.tsx — the classes each value applies are there.
variant	'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive'	'primary'	Chooses this element’s variant from buttonVariants’s presets, declared in packages/ui/src/components/button.tsx — the classes each value applies are there.

Also carries every prop of Omit<PressableProps, 'accessibilityRole' | 'role' | 'children'> — that upstream contract is not reproduced here.

PopoverContentProps

Prop	Type	Default	Description
align	PopoverAlign	'center'	Where the overlay sits along the anchor’s cross axis — 'start', 'center' or 'end'. The anchored-overlay kernel may flip it when the preferred placement would collide with the viewport.
alignOffset	number	0	Pixels to shift the overlay along the alignment axis, after align is resolved.
avoidKeyboard	boolean	false	Whether the overlay repositions to stay clear of the on-screen keyboard.
avoidSafeArea	boolean	true	Whether the overlay keeps clear of the platform safe-area insets — notches, home indicators and status bars.
closeOnOutsidePress	boolean	true	Whether a press outside the overlay dismisses it.
collisionPadding	PopoverCollisionPadding	8	Minimum distance to keep from the viewport edges when the kernel repositions or flips the overlay. A number applies to every edge; an object sets edges individually.
direction	PopoverDirection	—	Logical direction used to resolve align/placement for RTL layouts. Defaults to the app’s resolved layout direction.
flip	boolean	true	Flips placement to the opposite side of the trigger when there is not enough room. Defaults to true.
outsidePressProps	Omit<PressableProps, 'children' | 'onPress' | 'style'>	—	Forwarded to the outside-press dismiss layer, excluding children/onPress/style, which this component owns.
outsidePressTestID	string	—	testID applied to the outside-press dismiss layer, for targeting it in tests.
placement	PopoverPlacement	'bottom'	Which side of the trigger the popover opens on. Defaults to 'bottom'.
shift	boolean	true	Shifts the popover along the trigger’s edge to stay within the viewport instead of overflowing. Defaults to true.
sideOffset	number	8	Pixels of gap between the anchor and the overlay, along the placement side.

Also carries every prop of Omit<ViewProps, 'accessibilityViewIsModal' | 'role'> — that upstream contract is not reproduced here.

PopoverDescriptionProps

This type adds no fields of its own. These are the props the implementation reads from the base type below; everything else is passed straight through.

Prop	Default
accessibilityLabel	—
children	—
className	—
nativeID	—

Also carries every prop of Omit<TextProps, 'tone' | 'variant'> — documented on the Text page, not reproduced here.

PopoverProps

one of the following mutually exclusive variants:

Variant PopoverControlledProps:

Prop	Type	Default	Description
children	React.ReactNode	—	Content rendered inside this element. The family’s composition section states which children it expects.
defaultOpen	never	false	Not accepted in the controlled variant, where open already owns the state. Pass defaultOpen on its own, without open, to use the uncontrolled variant.
onOpenChange (required)	(open: boolean) => void	—	Applies a requested open state, and is required here because the controlled variant never updates its own visibility. If this does not change open, nothing does.
open (required)	boolean	—	Current open state, owned by the caller; supplying a defined value alongside onOpenChange is what selects the controlled variant. Passing open without an onOpenChange function warns in development and falls back to uncontrolled behavior.

Variant PopoverUncontrolledProps:

Prop	Type	Default	Description
children	React.ReactNode	—	Content rendered inside this element. The family’s composition section states which children it expects.
defaultOpen	boolean	false	Open state to start from, read once when the component mounts, so later changes to it are ignored. Defaults to false; drive visibility with open + onOpenChange instead when it needs to change.
onOpenChange	(open: boolean) => void	—	Notified after the open state changes, and optional here because the uncontrolled variant updates its own state either way.
open	undefined	—	Must be left undefined in the uncontrolled variant, because a defined open together with onOpenChange selects the controlled variant instead.

PopoverTitleProps

This type adds no fields of its own. These are the props the implementation reads from the base type below; everything else is passed straight through.

Prop	Default
accessibilityLabel	—
children	—
className	—
nativeID	—

Also carries every prop of Omit<TextProps, 'accessibilityRole' | 'role' | 'variant'> — documented on the Text page, not reproduced here.

PopoverTriggerProps

PopoverTriggerProps is exactly ButtonProps.

Prop	Type	Default	Description
children	React.ReactNode	—	Content rendered inside this element. The family’s composition section states which children it expects.
className	string	—	Extra utility classes, merged after the component’s own via cn(...), so they win on conflict. An escape hatch for source-owned and application work, not a cross-engine portability guarantee.
labelClassName	string	—	Extra utility classes for the label text specifically, merged after the component’s own.
loading	boolean	false	Shows a spinner in place of the label, sets aria-busy, and disables presses. Defaults to false.
size	'sm' | 'md' | 'lg' | 'icon'	'md'	Chooses this element’s size from buttonVariants’s presets, declared in packages/ui/src/components/button.tsx — the classes each value applies are there.
variant	'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive'	'primary'	Chooses this element’s variant from buttonVariants’s presets, declared in packages/ui/src/components/button.tsx — the classes each value applies are there.

Also carries every prop of Omit<PressableProps, 'accessibilityRole' | 'role' | 'children'> — that upstream contract is not reproduced here.

This is the pressable itself — the same variant/size/press API as Button — so icon/label children go directly inside it. Do not nest a second pressable (an icon button, or an avatar wrapped for press) inside a *Trigger: on Web that renders one interactive element inside another, which React flags as invalid DOM nesting. For an icon-only or avatar trigger, set variant="ghost" (and size/className as needed) on the trigger itself instead of wrapping a second pressable.

Related exported types:

• PopoverAlign — alias of AnchoredOverlayAlign.
• PopoverCollisionPadding — alias of AnchoredOverlayCollisionPadding.
• PopoverDirection — alias of AnchoredOverlayDirection.
• PopoverPlacement — alias of AnchoredOverlayPlacement.

The executable fixtures below are the source-grounded usage examples; consumers should not infer state ownership from DOM structure or another UI library.

Provider and dependencies

• BeeUIProvider is required above this family because it participates in shared overlay/toast runtime infrastructure.
• Peer/native dependencies visible to this Registry item: react, react-native
• Registry dependency closure: button, core-overlay, overlay-runtime, text, theme, use-direction
• Safe-area ownership remains explicit: shell surfaces touching system edges opt into SafeArea; components do not silently invent app-shell insets.
• Web consumers load the BeeUI semantic theme CSS as documented in Web onboarding.

Platform behavior

This family ships no platform-specific file, and its own source takes no Platform branch.

The same public family is exposed across the supported target matrix; meaningful platform differences remain governed by the compatibility contract.

Evidence classes are not equal and this page does not blur them: Web behavior is exercised in a real browser, while iOS and Android carry package/export and native-compile evidence, which is not device-runtime proof. The compatibility contract records which class each claim rests on.

Accessibility

• Roles this family assigns: dialog, header — set in popover.tsx by the components themselves, not by the caller.
• Accessibility states and properties it sets: accessibilityElementsHidden, accessibilityHint, accessibilityLabel, accessibilityLabelledBy, controls, expanded, hidden — read from popover.tsx.

Keyboard/focus behavior, announcements, Dynamic Type/Web zoom, RTL and reduced-motion expectations are not derived here — see Accessibility overview, Keyboard & focus, RTL/localization and Large text & zoom. BeeUI does not claim universal accessibility certification from automated tests.

Styling and theming

• Style axes: size (4 values), variant (5 values), tone (8 values, inherited from TextProps).
• Class-name surfaces: className, labelClassName.

Colors, spacing and typography come from semantic tokens rather than from values written here — see Theming and Density. A className is an escape hatch for source-owned and application work, not a cross-engine portability guarantee.

Executable examples

• Primary executable fixture: apps/showcase/__tests__/anchor-measurement-seam-proof.test.tsx
• Additional fixture: apps/showcase/__tests__/issue-149-reduced-motion-acceptance.test.tsx
• Additional fixture: apps/showcase/__tests__/issue-21-popover.test.tsx
• Additional fixture: apps/showcase/__tests__/issue-35-overlay-context.test.tsx

Addressable examples

Each link below opens the Showcase at that exact example, not at the top of the gallery:

• basic — smallest meaningful complete usage
• states — the states example
• composition — the composition example

The Showcase links demonstrate Web behavior; use the native-preview guide for real simulator/emulator/device paths.

Live Web preview

This frame loads the real BeeUI Web Showcase on demand; it is not a second docs-only implementation. It proves browser behavior only. Use native preview for iOS/Android simulator, emulator or device paths.

Composition anatomy

• Family root / primary export: Popover
  • Public composition parts / helpers:
    • PopoverClose
    • PopoverContent
    • PopoverDescription
    • PopoverTitle
    • PopoverTrigger
  • Exported type surface:
    • PopoverAlign
    • PopoverCloseProps
    • PopoverCollisionPadding
    • PopoverContentProps
    • PopoverDescriptionProps
    • PopoverDirection
    • PopoverPlacement
    • PopoverProps
    • PopoverTitleProps
    • PopoverTriggerProps

The tree above is ordinary document structure so it remains readable with keyboard and assistive technology; it is derived from the real public export family rather than a canvas-only diagram.

Verified example source

These are the parts of the typechecked runtime Showcase fixture behind this live preview — apps/showcase/component-gallery/component-gallery.tsx, 1103 lines — where Popover is actually used: 63 lines in 6 places, of 7 in total — open the fixture for the remaining 1. Each block is copied verbatim from the line range named above it, so it is the same executable source, not a retelling of it. Other uses of this family, and the parts of the file exercising other families, are not reproduced here.

Imports the examples below need (a filtered subset of the fixture’s own top-level imports):

import { BeeThemeScope, Field, Input, Popover, PopoverClose, PopoverContent, PopoverDescription, PopoverTitle, PopoverTrigger, Text } from '@beemvp/beeui-ui';
import * as React from 'react';
import { useUniwind } from 'uniwind';

Placeholder for a prop this fixture receives (not fixture source — substitute your own handler):

const placement: 'top' | 'right' | 'bottom' | 'left' = undefined as never;

lines 150–168:

    <Popover>
      <PopoverTrigger size="sm" variant="outline">
        {placement}
      </PopoverTrigger>
      <PopoverContent placement={placement} testID={`popover-${placement}-content`}>
        <PopoverTitle>{`${placement[0].toUpperCase()}${placement.slice(1)} placement`}</PopoverTitle>
        <PopoverDescription>
          This surface is positioned by the shared anchored-overlay geometry kernel.
        </PopoverDescription>
        {placement === 'bottom' ? (
          <Field label="Note">
            <Input accessibilityLabel="Popover note" testID="popover-demo-input" />
          </Field>
        ) : null}
        <PopoverClose size="sm" variant="ghost">
          Close
        </PopoverClose>
      </PopoverContent>
    </Popover>

Fixture state this block reads (same file, lines 174, 176-178, 191):

const OverlayConsumerContext = React.createContext('overlay-context-default');
function OverlayContextValue({ testID }: { testID: string }) {
  return <Text testID={testID}>{`context: ${React.useContext(OverlayConsumerContext)}`}</Text>;
}
  const [rootOpen, setRootOpen] = React.useState(false);

lines 206–213:

      <Popover onOpenChange={setRootOpen} open={rootOpen}>
        <PopoverTrigger testID="overlay-context-casec-root-trigger" variant="outline">
          CASE C root
        </PopoverTrigger>
        <PopoverContent placement="bottom">
          <OverlayContextValue testID="overlay-context-casec-root-value" />
        </PopoverContent>
      </Popover>

Fixture state this block reads (same file, lines 174, 176-178):

const OverlayConsumerContext = React.createContext('overlay-context-default');
function OverlayContextValue({ testID }: { testID: string }) {
  return <Text testID={testID}>{`context: ${React.useContext(OverlayConsumerContext)}`}</Text>;
}

lines 239–247:

        <Popover>
          <PopoverTrigger testID="overlay-context-popover-trigger" variant="outline">
            Popover context
          </PopoverTrigger>
          <PopoverContent placement="bottom">
            <PopoverTitle>Popover consumer context</PopoverTitle>
            <OverlayContextValue testID="overlay-context-popover-value" />
          </PopoverContent>
        </Popover>

Fixture state this block reads (same file, lines 174, 176-178):

const OverlayConsumerContext = React.createContext('overlay-context-default');
function OverlayContextValue({ testID }: { testID: string }) {
  return <Text testID={testID}>{`context: ${React.useContext(OverlayConsumerContext)}`}</Text>;
}

lines 272–279:

            <Popover>
              <PopoverTrigger testID="overlay-context-dialog-popover-trigger" variant="outline">
                Popover in dialog
              </PopoverTrigger>
              <PopoverContent placement="bottom">
                <OverlayContextValue testID="overlay-context-dialog-popover-value" />
              </PopoverContent>
            </Popover>

Fixture state this block reads (same file, line 321-324):

function ThemeScopeValue({ testID }: { testID: string }) {
  const { theme } = useUniwind();
  return <Text testID={testID}>{`theme: ${theme}`}</Text>;
}

lines 333–341:

          <Popover>
            <PopoverTrigger testID="theme-scope-popover-trigger" variant="outline">
              Popover in scope
            </PopoverTrigger>
            <PopoverContent placement="bottom">
              <PopoverTitle>Popover in a BeeThemeScope</PopoverTitle>
              <ThemeScopeValue testID="theme-scope-popover-value" />
            </PopoverContent>
          </Popover>

lines 878–887:

                  <Popover>
                    <PopoverTrigger variant="outline">Near right edge</PopoverTrigger>
                    <PopoverContent align="start" placement="right" sideOffset={12}>
                      <PopoverTitle>Collision-aware placement</PopoverTitle>
                      <PopoverDescription>
                        Preferred placement is right; the resolver flips or shifts only when the viewport requires it.
                      </PopoverDescription>
                      <PopoverClose size="sm" variant="ghost">Close</PopoverClose>
                    </PopoverContent>
                  </Popover>

Open the fixture itself for the full surrounding component. For a smaller app-specific example, start from the imports and fixture-state blocks above and keep only the state your screen owns.

Limitations

• Passing open without onOpenChange leaves the value read-only: the component renders what you passed and can never change it. It warns in development builds rather than failing silently in production.

Related

• All components
• Production patterns
• Showcase
• CLI & source ownership
• Source