Popover

Popover is a versatile overlay component used to display contextual content or interactive elements anchored to a trigger. It supports portal rendering, automatic positioning, and accessibility features like ARIA compliance and focus management.

---

Usage

Basic usage

import { Popover, PopoverTrigger, PopoverContent } from '@nofinite/nui';

<Popover>
  <PopoverTrigger>Info</PopoverTrigger>
  <PopoverContent>Simple content</PopoverContent>
</Popover>;

With typical interaction

<Popover>
  <PopoverTrigger>Details →</PopoverTrigger>
  <PopoverContent placement="right">
    More details here.
    <PopoverClose>OK</PopoverClose>
  </PopoverContent>
</Popover>

---

Variants

Popover itself does not have visual variants, but content placement and trigger styling can be customized.

<PopoverContent placement="top">Top content</PopoverContent>
<PopoverContent placement="bottom">Bottom content</PopoverContent>
<PopoverContent placement="left">Left content</PopoverContent>
<PopoverContent placement="right">Right content</PopoverContent>

Available placements:

• top – displays popover above the trigger
• bottom – displays popover below the trigger (default)
• left – displays popover to the left of the trigger
• right – displays popover to the right of the trigger

Guidelines:

• Use top/bottom for vertical alignment with ample space.
• Use left/right for horizontal alignment or narrow containers.

---

Sizes

PopoverContent adapts to its content with min/max width constraints:

<PopoverContent style={{ minWidth: 200, maxWidth: 320 }}>
  Content
</PopoverContent>

• Minimum width: 200px
• Maximum width: 320px
• Height adjusts based on content

---

States

Popover supports open/closed states and can display a close button:

<PopoverContent>Open state</PopoverContent>
<PopoverClose>Close</PopoverClose>

• open – determines if content is visible
• disabled – not applicable by default; disable trigger via custom props
• loading / error – can be implemented inside content if needed

---

Native Props / Composition

PopoverTrigger and PopoverClose accept standard HTML attributes:

<PopoverTrigger className="my-trigger" aria-label="Open info popover" />
<PopoverClose className="my-close" onClick={() => console.log("Closed")} />

PopoverContent supports portal rendering and inline styles for positioning:

<PopoverContent style={{ top: 100, left: 200 }}>
  Positioned content
</PopoverContent>

---

Props

Prop	Type	Default	Description
children	React.ReactNode	—	Content rendered inside the component
className	string	""	Additional class names for custom styling
placement	"top" | "bottom" | "left" | "right"	bottom	Where the popover content appears relative to trigger
offset	number	8	Distance in pixels between trigger and content
...rest	React.HTMLAttributes<HTMLElement>	—	Any other forwarded native attributes

---

Behavior Notes

• Popover restores focus to the trigger on close.
• Click outside or pressing Escape closes the popover.
• Positions are automatically calculated relative to the trigger.
• Content is rendered inside a portal to avoid clipping by parent containers.

<Popover>
  <PopoverTrigger>Trigger</PopoverTrigger>
  <PopoverContent placement="right">Content</PopoverContent>
</Popover>

---

Accessibility

• Trigger renders as <button> with aria-haspopup="dialog" and aria-expanded.
• Content renders as <div role="dialog" aria-modal="false">.
• Focus is trapped and restored to trigger when popover closes.
• ESC closes the popover for keyboard users.
• Close button is focusable and accessible.

<PopoverTrigger aria-label="Open details popover">Details</PopoverTrigger>

---

Layout

• PopoverTrigger is inline-block by default.
• PopoverContent is absolutely positioned via portal.
• Can be full-width by overriding styles:

<PopoverContent style={{ width: '100%' }}>Full-width content</PopoverContent>

• Content respects min-width and max-width.

---

Best Practices

Do

• Use for contextual information, tooltips, or small interactive panels.
• Place popover near related UI element for clarity.
• Always provide meaningful labels for triggers.

Don’t

• Don’t overload popover with large content.
• Avoid nesting multiple popovers without proper management.
• Don’t rely solely on visual cues; use ARIA attributes.