ts
| Guidance | Practices |
|---|---|
| Do | Keep popover content focused on a single task or piece of information. |
| Do | Provide a clear way to close — either by clicking outside or with an explicit close button. |
| Don't | Nest popovers inside other popovers — it creates confusing focus and navigation. |
| Don't | Use a popover for content that requires heavy user input — use a Dialog instead. |
| Don't | Put too much content in a popover — if it needs scrolling, use a Dialog instead. |
| Prop | Type | Description |
|---|---|---|
contentrequired | ReactNode | Content to display inside the popover. |
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. |
placement | LayerPlacement (default: 'below') | Position placement relative to the trigger. |
alignment | LayerAlignment (default: 'start') | Alignment along the placement axis. |
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. |
label | string | Accessible label for the popover 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 auto-focus the first focusable element when the popover opens. Set to false for inline showcases or documentation previews. |
xstyle | StyleXStyles | StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}. |