overlays / stable

Popover

Floating panel anchored to a trigger for quick edits, pickers and previews.

LIVE PREVIEW

Loading preview…

When to use

Inline editing of one property (assignee, due date, estimate).
Small forms and previews tied to a control.

Consider an alternative

A list of actions — use Menu.
A text hint — use Tooltip.
A task that must block the page — use Dialog.

Import

import { Popover } from '@revido-llc/kit';

Keyboard interaction

Enter / Space on the trigger — open
Escape — close and return focus

Props

Props documented by the Kit. Refer to the TypeScript types for the complete interface, including inherited props.


aria-label	string	—	Accessible name for the popover dialog when its content has no heading.
children	ReactNode \| ((opts: DialogRenderProps) => ReactNode)	—
className	string	—	Classes for the popover surface (padding defaults to `p-3`).
arrowBoundaryOffset	number	0	The minimum distance the arrow's edge should be from the edge of the overlay element.
arrowRef	RefObject<Element>	—	A ref for the popover arrow element.
boundaryElement	Element	document.body	Element that that serves as the positioning boundary.
containerPadding	number	12	The placement padding that should be applied between the element and its surrounding container.
crossOffset	number	0	The additional offset applied along the cross axis between the element and its anchor element.
getTargetRect	((target: Element) => DOMRect)	target.getBoundingClientRect()	Overrides the target element's bounding rectangle. Useful for positioning relative to a specific point such as the mouse cursor (e.g. context menus) or text selection.
isEntering	boolean	—	Whether the popover is currently performing an entry animation.
isExiting	boolean	—	Whether the popover is currently performing an exit animation.
isKeyboardDismissDisabled	boolean	false	Whether pressing the escape key to close the popover should be disabled. Most popovers should not use this option. When set to true, an alternative way to close the popover with a keyboard must be provided.
isNonModal	boolean	—	Whether the popover is non-modal, i.e. elements outside the popover may be interacted with by assistive technologies. Most popovers should not use this option as it may negatively impact the screen reader experience. Only use with components such as combobox, which are designed to handle this situation carefully.
maxHeight	number	—	The maxHeight specified for the overlay element. By default, it will take all space up to the current viewport height.
offset	number	8	The additional offset applied along the main axis between the element and its anchor element.
placement	Placement	'bottom'	The placement of the element with respect to its anchor element.
render	DOMRenderFunction<"div", PopoverRenderProps>	—	Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
scrollRef	RefObject<Element>	overlayRef	A ref for the scrollable region within the overlay.
shouldCloseOnInteractOutside	((element: Element) => boolean)	—	When user interacts with the argument element outside of the popover ref, return true if onClose should be called. This gives you a chance to filter out interaction with elements that should not dismiss the popover. By default, onClose will always be called on interaction outside the popover ref.
shouldFlip	boolean	true	Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely.
shouldSkipAnimation	boolean	—	Whether the popover should appear and disappear without an entry or exit animation. This is used by components such as PreviewTrigger to skip animations when quickly swapping between overlays.
shouldUpdatePosition	boolean	true	Whether the overlay should update its position automatically.
trigger	string	—	The name of the component that triggered the popover. This is reflected on the element as the `data-trigger` attribute, and can be used to provide specific styles for the popover depending on which element triggered it.
triggerRef	RefObject<Element>	—	The ref for the element which the popover positions itself with respect to. When used within a trigger component such as DialogTrigger, MenuTrigger, Select, etc., this is set automatically. It is only required when used standalone.
UNSTABLE_portalContainer	Element	document.body	The container element in which the overlay portal will be placed. This may have unknown behavior depending on where it is portalled to.

Related exports

PopoverTrigger

Examples

Quick edit

Pick a value: it saves and closes. The current value is highlighted.

const [points, setPoints] = useState(3);
const [open, setOpen] = useState(false);
<PopoverTrigger isOpen={open} onOpenChange={setOpen}>
  <Button variant="outline" size="sm">Estimate: {points} pts</Button>
  <Popover aria-label="Edit estimate">
    {[1, 2, 3, 5, 8].map((v) => (
      <Button key={v} variant={v === points ? "primary" : "outline"} aria-pressed={v === points}
        onPress={() => { setPoints(v); setOpen(false); }}>{v}</Button>
    ))}
  </Popover>
</PopoverTrigger>

Placements

<Popover placement="top" aria-label="Details">…</Popover>

Literal anatomy

Static component anatomy; bind events in the consuming app.

<PopoverTrigger><Button>Details</Button><Popover>Ready for review.</Popover></PopoverTrigger>