use-floating-panel

Installation

Usage

useFloatingPanel runs the full lifecycle of a popover="manual" panel: it calls showPopover() / hidePopover() as open changes, closes on outside mousedown (optionally ignoring presses on an anchor element), saves the previously focused element on open and restores it on close when focus would otherwise be lost.

It is the headless counterpart of PopoverContent — Popover, Picker and Select run this exact hook internally. Reach for it when you assemble your own anchored panel from primitives:

import { useRef, useState } from "react";
import { useFloatingPanel } from "@/ui";

function MyPanel() {
  const [open, setOpen] = useState(false);
  const panelRef = useRef<HTMLDivElement>(null);

  useFloatingPanel({
    open,
    panelRef,
    onOpenChange: setOpen,
    restoreFocus: true,
  });

  return (
    <div ref={panelRef} popover="manual" className="not-open:hidden">
      {/* panel content */}
    </div>
  );
}

Escape handling is intentionally left to the call site (via onKeyDown), because keyboards interact with panels differently — an input-driven picker closes on the input's Escape, a menu closes on the panel's.

API Reference

Options (UseFloatingPanelOptions)