@mshafiqyajid/react-popover

Headless popover hook and styled component for React. Accessible, click or hover triggered, portal-based positioning, animated, SSR-safe, fully typed.

Full docs →

Installation

npm install @mshafiqyajid/react-popover

Usage — Headless

import { usePopover } from "@mshafiqyajid/react-popover";

function MyPopover() {
  const { triggerProps, popoverProps, isOpen } = usePopover({ placement: "bottom" });

  return (
    <>
      <button {...triggerProps}>Open</button>
      {isOpen && (
        <div {...popoverProps}>Popover content</div>
      )}
    </>
  );
}

Usage — Styled

import { PopoverStyled } from "@mshafiqyajid/react-popover/styled";
import "@mshafiqyajid/react-popover/styles.css";

function App() {
  return (
    <PopoverStyled
      content={<p>Rich content here</p>}
      title="Popover Title"
      placement="bottom-start"
      offset={8}
      collisionPadding={12}
      flip
      shift
      strategy="absolute"
    >
      <button>Click me</button>
    </PopoverStyled>
  );
}

Positioning

| Prop | Type | Default | Description | |---|---|---|---| | placement | top \| bottom \| left \| right plus each with -start / -end | "bottom" | Preferred side and alignment | | offset | number | 8 | Gap in px between trigger and popover | | collisionPadding | number | 8 | Viewport edge margin for flip / shift | | flip | boolean | true | Auto-flip to opposite side when there's no room | | shift | boolean | true | Push back into view along the cross-axis | | strategy | "absolute" \| "fixed" | "absolute" | Positioning strategy |

data-placement on the rendered popover reflects the resolved placement after flip — style by it (e.g. arrow direction, side-specific radius).

License

MIT

What's new in 0.3.0

• Virtual element anchoring — anchor: { getBoundingClientRect: () => DOMRect } | null lets you anchor at a cursor position / selection rect / arbitrary point instead of children.
• --rpv-arrow-bg / --rpv-arrow-border CSS vars — themed popovers can now keep arrow colour in sync with the body.
• returnFocus (default true) — restores focus to the trigger on close.
• closeWhenAnchorHidden — auto-close when the trigger scrolls out of the viewport (IntersectionObserver-driven).
• modal: true — modal-popover variant. Sets aria-modal="true" on the popover and traps Tab focus inside the body.