Popover

Usage

• Use Popovers for supplementary content too long for a Tooltip but not significant enough for a Modal or separate page.
• Use Popovers for both static text and interactive elements such as buttons, links, or forms.
• Use a Tooltip for short, non-interactive helper text that appears on hover/focus.
• Use a Modal when the user must complete a focused task before returning to the page.
• Never nest Popovers within other Popovers. Rework the flow or use a Modal instead.

Appearance

• Display the arrow by default (withArrow={true}) to visually connect the Popover to its trigger.
• Hide the arrow (withArrow={false}) only when the trigger association is already evident from context.

Trigger styles

• Use PopoverTrigger for inline text triggers that blend with surrounding content.
• Add isUnderlined to PopoverTrigger to make the trigger visually distinct within body text.
• Use PopoverTriggerButton for a prominent button-style trigger. It extends all Button props.
• Use the as prop on PopoverTrigger to render a custom element (e.g., as={Button}) as the trigger.

Behaviors

• Popovers open on click by default (shouldTriggerOnClick={true}).
• Enable hover opening (shouldTriggerOnHover={true}) only when absolutely necessary. Hover-opened Popovers appear after a 250ms delay by default.
• Set placement to "top", "bottom" (default), "left", or "right". Placement is a preference; the Popover repositions automatically to remain visible in smaller viewports.
• Popovers dismiss on outside click, Escape key, and focus loss by default.
• Disable close-on-focus-loss (shouldCloseOnFocusOut={false}) to create a persistent Popover that requires an explicit click outside or Escape to dismiss.
• Enable dragging (isDraggable={true}) to let users reposition the Popover. Render a PopoverPrimitiveDragHandle inside PopoverContent to provide the drag handle.
• Customize the animation duration (animationTransitionDuration) in milliseconds. Default is 125.
• Control open state externally with isOpen paired with onOpenChange.
• Set an initial open state without controlling it via defaultIsOpen.

Content

• Write headers and descriptions in sentence case.
• Provide a clear header that summarizes the topic. Do not repeat the trigger text without adding context.
• Limit Popover content to 1-3 sentences. Use a Modal or inline content for longer text.
• Label interactive elements with specific action verbs (e.g., "Resume campaign"). Never use generic labels like "OK" or "Click here".

Implementation Notes

• Popover supports a shorthand API: pass header and description (string props) directly to Popover for simple text-only content without composing subcomponents.
• For rich or interactive content, compose PopoverContent, PopoverContentHeader, and PopoverContentDescription as children alongside the trigger.
• PopoverTriggerButton extends Button — pass any Button prop (e.g., variant, size, icon, iconPosition) directly to it.
• The content prop is deprecated. Use description instead.
• React passes content via children. Ember yields via the default block ({{yield}}).
• In Ember, use @ prefix for all args: <PlumaPopover @placement="bottom" @withArrow={{false}}>.
• unsafe_popoverClassName, unsafe_popoverContentClassName, and unsafe_popoverStyle exist for last-resort styling overrides.