ui/components/floating-panel

Floating Panel

Headless floating surface primitive. Composes Portal, presence, and floating-position to render an anchored, animated panel with data-state, data-side, data-align, and data-positioned attributes plus a transform-origin custom property. Used by Popover, Select, and other anchored surfaces.

Preview

tsx

1 "use client";2 3 import { type KeyboardEvent, useEffect, useId, useRef, useState } from "react";4 import { FloatingPanel, useFloatingPanelContext } from "@/components/ui/floating-panel";5 6 export default function FloatingPanelDefaultExample() {7   const [open, setOpen] = useState(false);8   const triggerRef = useRef<HTMLButtonElement>(null);9   const panelId = useId();10   const titleId = useId();11 12   const close = () => {13     setOpen(false);14     triggerRef.current?.focus();15   };16 17   const handlePanelKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {18     if (event.key !== "Escape") return;19     event.preventDefault();20     close();21   };22 23   return (24     <div className="flex items-center gap-4">25       <button26         ref={triggerRef}27         type="button"28         aria-haspopup="dialog"29         aria-expanded={open}30         aria-controls={open ? panelId : undefined}31         onClick={() => setOpen((value) => !value)}32         className="border border-foreground/30 px-3 py-1 font-mono text-sm focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-0"33       >34         {open ? "close" : "open panel"}35       </button>36 37       <FloatingPanel38         open={open}39         triggerRef={triggerRef}40         role="dialog"41         aria-labelledby={titleId}42         id={panelId}43         onKeyDown={handlePanelKeyDown}44         className="rounded-sm border border-border bg-background p-3 font-mono text-xs text-foreground"45       >46         <DialogContent titleId={titleId} onDismiss={close} />47       </FloatingPanel>48     </div>49   );50 }51 52 function DialogContent({ titleId, onDismiss }: { titleId: string; onDismiss: () => void }) {53   const { positioned } = useFloatingPanelContext();54   const dismissRef = useRef<HTMLButtonElement>(null);55 56   useEffect(() => {57     if (positioned) dismissRef.current?.focus();58   }, [positioned]);59 60   return (61     <>62       <p id={titleId} className="font-bold">63         Quick info64       </p>65       <p>Anchored panel content.</p>66       <button67         ref={dismissRef}68         type="button"69         className="mt-2 block border border-foreground/30 px-2 py-0.5 text-xs focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-0"70         onClick={onDismiss}71       >72         dismiss73       </button>74     </>75   );76 }77

Installation

$pnpm exec dgadd add ui/floating-panel

[Installs to]src/components/ui/floating-panel[Item]ui/floating-panel

dgadd is not public on npm yet. Until the first release, pack @diffgazer/add from the repository and install that tarball into this app, which is what puts dgadd on pnpm exec.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS once packages are available.

Usage

tsx

1 "use client";2 3 import { type KeyboardEvent, useEffect, useId, useRef, useState } from "react";4 import { FloatingPanel, useFloatingPanelContext } from "@/components/ui/floating-panel";5 6 export default function FloatingPanelDefaultExample() {7   const [open, setOpen] = useState(false);8   const triggerRef = useRef<HTMLButtonElement>(null);9   const panelId = useId();10   const titleId = useId();11 12   const close = () => {13     setOpen(false);14     triggerRef.current?.focus();15   };16 17   const handlePanelKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {18     if (event.key !== "Escape") return;19     event.preventDefault();20     close();21   };22 23   return (24     <div className="flex items-center gap-4">25       <button26         ref={triggerRef}27         type="button"28         aria-haspopup="dialog"29         aria-expanded={open}30         aria-controls={open ? panelId : undefined}31         onClick={() => setOpen((value) => !value)}32         className="border border-foreground/30 px-3 py-1 font-mono text-sm focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-0"33       >34         {open ? "close" : "open panel"}35       </button>36 37       <FloatingPanel38         open={open}39         triggerRef={triggerRef}40         role="dialog"41         aria-labelledby={titleId}42         id={panelId}43         onKeyDown={handlePanelKeyDown}44         className="rounded-sm border border-border bg-background p-3 font-mono text-xs text-foreground"45       >46         <DialogContent titleId={titleId} onDismiss={close} />47       </FloatingPanel>48     </div>49   );50 }51 52 function DialogContent({ titleId, onDismiss }: { titleId: string; onDismiss: () => void }) {53   const { positioned } = useFloatingPanelContext();54   const dismissRef = useRef<HTMLButtonElement>(null);55 56   useEffect(() => {57     if (positioned) dismissRef.current?.focus();58   }, [positioned]);59 60   return (61     <>62       <p id={titleId} className="font-bold">63         Quick info64       </p>65       <p>Anchored panel content.</p>66       <button67         ref={dismissRef}68         type="button"69         className="mt-2 block border border-foreground/30 px-2 py-0.5 text-xs focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-0"70         onClick={onDismiss}71       >72         dismiss73       </button>74     </>75   );76 }77

FloatingPanel never closes itself. Wrap it in a primitive that owns dismiss (outside-click, escape, focus) and forward the resolved open boolean. The custom menu example below shows the pattern.

Examples

Custom menu

Preview

tsx

1 "use client";2 3 import { type KeyboardEvent, useEffect, useId, useRef, useState } from "react";4 import { FloatingPanel, useFloatingPanelContext } from "@/components/ui/floating-panel";5 // @hidden-imports-ok — demo imports the useNavigation re-export from the hidden hook registry item.6 import { useNavigation } from "@/hooks/use-navigation";7 import { useOutsideClick } from "@/hooks/use-outside-click";8 // @hidden-imports-ok: the keys registry installs this utility at the copied local path.9 import { getTabbableElements } from "@/hooks/utils/focusable";10 11 const ITEMS = ["Open", "Duplicate", "Delete"] as const;12 13 export default function FloatingPanelCustomMenuExample() {14   const [open, setOpen] = useState(false);15   const triggerRef = useRef<HTMLButtonElement>(null);16   const panelRef = useRef<HTMLDivElement>(null);17   const menuId = useId();18   const { onKeyDown: navigateMenu } = useNavigation({19     containerRef: panelRef,20     role: "menuitem",21     moveFocus: true,22     wrap: true,23   });24 25   const close = () => {26     setOpen(false);27     triggerRef.current?.focus();28   };29 30   useOutsideClick(panelRef, () => setOpen(false), open, [triggerRef]);31 32   const handleMenuKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {33     switch (event.key) {34       case "Tab": {35         event.preventDefault();36         setOpen(false);37         const trigger = triggerRef.current;38         if (!trigger) break;39 40         const tabbableElements = getTabbableElements(trigger.ownerDocument.body);41         const triggerIndex = tabbableElements.indexOf(trigger);42         const targetIndex = triggerIndex + (event.shiftKey ? -1 : 1);43         tabbableElements[targetIndex]?.focus();44         break;45       }46       case "Escape":47         event.preventDefault();48         close();49         break;50       default:51         navigateMenu(event);52         break;53     }54   };55 56   return (57     <div className="flex items-center gap-4">58       <button59         ref={triggerRef}60         type="button"61         aria-haspopup="menu"62         aria-expanded={open}63         aria-controls={open ? menuId : undefined}64         onClick={() => setOpen((value) => !value)}65         className="border border-foreground/30 px-3 py-1 font-mono text-sm focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-0"66       >67         actions68       </button>69 70       <FloatingPanel71         ref={panelRef}72         open={open}73         triggerRef={triggerRef}74         role="menu"75         aria-label="Actions"76         id={menuId}77         sideOffset={4}78         onKeyDown={handleMenuKeyDown}79         className="min-w-[10rem] rounded-sm border border-border bg-background px-1 py-1 font-mono text-xs text-foreground"80       >81         <MenuItems onSelect={close} />82       </FloatingPanel>83     </div>84   );85 }86 87 function MenuItems({ onSelect }: { onSelect: () => void }) {88   const { positioned } = useFloatingPanelContext();89   const firstItemRef = useRef<HTMLButtonElement>(null);90 91   useEffect(() => {92     if (positioned) firstItemRef.current?.focus();93   }, [positioned]);94 95   return (96     <ul role="presentation" className="list-none">97       {ITEMS.map((item, index) => (98         <li key={item} role="presentation">99           <button100             ref={index === 0 ? firstItemRef : undefined}101             type="button"102             role="menuitem"103             data-value={item.toLowerCase()}104             tabIndex={-1}105             onClick={onSelect}106             className="flex w-full items-center px-2 py-1 text-left hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-0"107           >108             {item}109           </button>110         </li>111       ))}112     </ul>113   );114 }115

Edge collision

Preview

tsx

1 "use client";2 3 import { type KeyboardEvent, useEffect, useId, useRef, useState } from "react";4 import { FloatingPanel, useFloatingPanelContext } from "@/components/ui/floating-panel";5 6 const TRIGGER_CLASS =7   "border border-foreground/30 px-3 py-1 font-mono text-sm focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-0";8 9 export default function FloatingPanelCollisionExample() {10   return (11     <div className="flex w-full items-center justify-between gap-4">12       <EdgePanel side="left" label="open left-edge panel" />13       <EdgePanel side="right" label="open right-edge panel" />14     </div>15   );16 }17 18 function EdgePanel({ side, label }: { side: "left" | "right"; label: string }) {19   const [open, setOpen] = useState(false);20   const triggerRef = useRef<HTMLButtonElement>(null);21   const panelId = useId();22   const titleId = useId();23 24   const close = () => {25     setOpen(false);26     triggerRef.current?.focus();27   };28 29   const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {30     if (event.key !== "Escape") return;31     event.preventDefault();32     close();33   };34 35   return (36     <>37       <button38         ref={triggerRef}39         type="button"40         aria-haspopup="dialog"41         aria-expanded={open}42         aria-controls={open ? panelId : undefined}43         onClick={() => setOpen((value) => !value)}44         className={TRIGGER_CLASS}45       >46         {open ? "close" : label}47       </button>48 49       <FloatingPanel50         open={open}51         triggerRef={triggerRef}52         role="dialog"53         aria-labelledby={titleId}54         id={panelId}55         side={side}56         onKeyDown={handleKeyDown}57         className="w-64 rounded-sm border border-border bg-background p-3 font-mono text-xs text-foreground"58       >59         <CollisionDialogContent open={open} titleId={titleId} side={side} onDismiss={close} />60       </FloatingPanel>61     </>62   );63 }64 65 function CollisionDialogContent({66   open,67   titleId,68   side,69   onDismiss,70 }: {71   open: boolean;72   titleId: string;73   side: "left" | "right";74   onDismiss: () => void;75 }) {76   const { positioned } = useFloatingPanelContext();77   const dismissRef = useRef<HTMLButtonElement>(null);78 79   useEffect(() => {80     if (open && positioned) dismissRef.current?.focus();81   }, [open, positioned]);82 83   return (84     <>85       <p id={titleId} className="font-bold">86         Collision handling87       </p>88       <p className="mt-1">89         Requested side="{side}". With no room on that side the panel flips to the opposite side,90         then shifts to stay inside the viewport. The resolved values land on data-side and91         data-align.92       </p>93       <button94         ref={dismissRef}95         type="button"96         onClick={onDismiss}97         className="mt-3 border border-foreground/30 px-2 py-1 focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-0"98       >99         close panel100       </button>101     </>102   );103 }104

API Reference

FloatingPanel

Name	Type	Default	Description
openrequired	boolean	—	Controlled open state. FloatingPanel never closes itself; the wrapping primitive owns dismiss and forwards the resolved boolean here.
triggerRefrequired	RefObject<HTMLElement \| null>	—	Anchor element the panel positions against. Must be a stable RefObject.
side	"top" \| "bottom" \| "left" \| "right"	"bottom"	Preferred side relative to the trigger.
align	"start" \| "center" \| "end"	"center"	Alignment along the chosen side.
sideOffset	number	6	Pixel gap from the trigger along the side axis.
alignOffset	number	0	Pixel offset along the alignment axis.
avoidCollisions	boolean	true	Flips to the opposite side, then cross-axis sides, then shifts within the viewport. When false the panel is also left uncapped — no `max-width`/`max-height` is emitted.
collisionPadding	number	8	Minimum gap between the panel and the viewport edge during collision avoidance.
matchTriggerWidth	boolean	false	When true, exposes `--ui-floating-trigger-width` on the panel so callers can size the panel against the trigger (use as `width`, `min-width`, or `max-width`).
exitFallbackMs	number	1000	Max ms to wait for `animationend` before forcing unmount. Raise to at least 2× `--ui-content-exit-duration` if you customize that token past 500ms.
portalContainer	Element \| null	—	Explicit portal target forwarded to Portal. Falls back to the ambient PortalContainerProvider scope, then the scoped container's `ownerDocument.body`, then `document.body`.
onExitComplete	() => void	—	Fired after the exit animation resolves (or the fallback timer fires) and the panel unmounts.
style	CSSProperties	—	Caller styles merged before internal positioning styles. Structural keys cannot be overridden; pass-through keys (background, border, transform, etc.) apply.
className	string	—	Additional class names merged after the default `ui-floating-panel` class.
children	ReactNode	—	Panel body content.
ref	Ref<HTMLDivElement>	—	Forwarded ref to the panel element. Composed with the internal measurement ref.

useFloatingPanelContext

Name	Type	Default	Description
positionedrequired	boolean	—	True once a viewport position has been resolved and the panel has measured against its trigger; false during the first paint and after the exit animation. Use to defer effects (focus, measurement) until after the first measure.
siderequired	"top" \| "bottom" \| "left" \| "right" \| null	—	Preferred side relative to the trigger; resolved after collision handling. Null before the first measure.
alignrequired	"start" \| "center" \| "end" \| null	—	Alignment along the chosen side; resolved align after collision handling. Null before the first measure.

Data attributes

Attribute	Applies to	Values	Description
data-state	FloatingPanel	"open" \| "closed"	Presence state for enter and exit animation selectors.
data-side	FloatingPanel	"top" \| "right" \| "bottom" \| "left"	Resolved side after collision handling.
data-align	FloatingPanel	"start" \| "center" \| "end"	Resolved alignment after collision handling.
data-positioned	FloatingPanel	present after first measurement	Marks a measured panel so adapters can defer effects until positioning is stable.
data-anchor-hidden	FloatingPanel	present while the trigger is scrolled out of view	Set when the trigger has left the viewport or a scroll ancestor. The panel stops painting while it is present.

CSS variables

Name	Default	Description
--ui-content-transform-origin	component-defined	Computed transform origin matching the resolved side and alignment.
--ui-floating-trigger-width	component-defined	Trigger width in pixels when matchTriggerWidth is true.
--floating-panel-available-height	component-defined	Available height before viewport overflow. Use as max-height with overflow-y: auto.
--floating-panel-available-width	component-defined	Available width before viewport overflow. Use as max-width with overflow-x: auto.
--ui-floating-z	var(--z-popover)	Layer token read by .ui-floating-panel for z-index.

Accessibility

FloatingPanel renders a bare <div>. Consumers must supply:

a role (for example "dialog", "menu", "listbox", "tooltip")
an accessible name via aria-label or aria-labelledby

Descendants of the rendered panel can read positioning state via useFloatingPanelContext():

tsx

const { positioned, side, align } = useFloatingPanelContext()

positioned is false until the first measure resolves. Use it to defer effects (focus, measurement) until after that first measure — this is how PopoverContent defers autoFocus.

Notes

Headless and Controlled

FloatingPanel never closes itself. There is no defaultOpen. Wrap it in a primitive that owns dismiss (outside-click, escape, focus management) and forward the resolved boolean to `open`.

Positioning

Resolves placement against `triggerRef` with `side`, `align`, `sideOffset`, and `alignOffset`. When `avoidCollisions` is true (default), the panel flips to the opposite side, then cross-axis sides, then shifts within the viewport. If no side fits, it takes the side that overflows least rather than the preferred one, and its size caps come from the padded viewport it is about to be shifted into — so a panel anchored to a trigger with no room left never collapses to zero. Final values land on `data-side` and `data-align`.

CSS Custom Properties

Always writes `--ui-content-transform-origin` derived from the resolved side/align plus `--floating-panel-available-height` and `--floating-panel-available-width` for capping overflow. When `matchTriggerWidth` is true, also writes `--ui-floating-trigger-width`. The `.ui-floating-panel` rule reads `--ui-floating-z` (default `var(--z-popover)`) for its z-index layer, so consumers can scope-override z without className overrides. Consumers can read or override these on the panel or an ancestor.

Anchor Tracking

The panel re-measures on scroll of every scrollable ancestor, on window scroll/resize, and on trigger/panel resize, so it stays attached while the page moves. Once the trigger scrolls fully out of the viewport or out of one of those scroll ancestors, collision clamping would park the panel against a viewport edge detached from its anchor; instead the panel marks itself `data-anchor-hidden` and stops painting (`opacity: 0`, `pointer-events: none`). It stays mounted and focusable so an open overlay never drops focus, and it paints again as soon as the anchor scrolls back into view.

Style Merging

Caller `style` merges before internal positioning styles. Structural keys (`position`, `top`, `left`, `visibility`, `max-width`, `max-height`, `--ui-content-transform-origin`, `--floating-panel-available-height`, `--floating-panel-available-width`, `--ui-floating-trigger-width`, plus `opacity`/`pointer-events`/`animation` while `data-anchor-hidden` is set) cannot be overridden; everything else (background, min-width, border, transform, etc.) passes through. When `data-anchor-hidden` clears, the inline `animation: none` is removed and any consumer CSS enter animation restarts from frame zero — a deliberate trade-off: the hidden panel must not paint mid-keyframe, at the cost of replaying the animation on un-hide. The `max-width`/`max-height` caps hold the panel inside the collision padding, and the panel is its own scroll container (`overflow: auto` from `.ui-floating-panel`), so content beyond either cap scrolls inside the panel instead of running off the viewport edge. A consumer who overrides `overflow` — e.g. a panel that intentionally paints outside its box — owns the resulting sizing. The caps are omitted entirely when `avoidCollisions` is false; the `--floating-panel-available-*` custom properties are still written, so an opted-out consumer can cap by hand.

Accessibility

FloatingPanel renders a bare div. Consumers must supply a role (e.g. `dialog`, `menu`) and an accessible name (`aria-label` or `aria-labelledby`).

Context

Descendants of the rendered panel can subscribe to positioning state via `useFloatingPanelContext()`. Useful for adapters that need to defer effects (focus, measurement) until after the first measure.

CSS variables

The panel reads these CSS custom properties from the .ui-floating-panel cascade. Override on the panel, an ancestor, or :root. The animation tokens collapse to fade under prefers-reduced-motion: reduce (see Theme).

Variable	Default	Purpose
`--ui-floating-z`	`var(--z-popover)`	z-index layer for the panel.
`--ui-content-enter-duration`	`60ms`	Read by every directional enter token.
`--ui-content-exit-duration`	`40ms`	Read by every directional exit token.
`--ui-content-enter-from-{top\|bottom\|left\|right}`	`ui-content-enter-fade var(--ui-content-enter-duration) linear`	Full `animation` shorthand the panel uses when entering from that side.
`--ui-content-exit-to-{top\|bottom\|left\|right}`	`ui-content-exit-fade var(--ui-content-exit-duration) linear forwards`	Full `animation` shorthand the panel uses when exiting toward that side.
`--ui-content-transform-origin`	set by `FloatingPanel`	Resolved from `data-side` and `data-align`. Read it from custom keyframes that animate `transform`.
`--ui-floating-trigger-width`	set by `FloatingPanel` when `matchTriggerWidth`	Width of the trigger in pixels. Use as `width`, `min-width`, or `max-width` on the panel.
`--floating-panel-available-height`	set by `FloatingPanel` on every measure	Available height before viewport overflow. Use as `max-height` with `overflow-y: auto`.
`--floating-panel-available-width`	set by `FloatingPanel` on every measure	Available width before viewport overflow. Use as `max-width` with `overflow-x: auto`.

Override one direction with a transform-based keyframe:

css

.my-panel[data-side="bottom"] {
  --ui-content-enter-from-top:
    my-slide-down var(--ui-content-enter-duration) cubic-bezier(0.22, 1, 0.36, 1);
}

@keyframes my-slide-down {
  from {
    opacity: 0;
    transform: translateY(-6px) scale(0.98);
    transform-origin: var(--ui-content-transform-origin);
  }
  to {
    opacity: 1;
    transform: none;
  }
}

Lower the panel below other surfaces by scoping --ui-floating-z:

css

.my-tooltip-host {
  --ui-floating-z: var(--z-dropdown);
}

Reduced motion

Under prefers-reduced-motion: reduce, the four --ui-content-enter-from-* tokens collapse to the fade-only keyframe (ui-content-enter-fade) and the four --ui-content-exit-to-* tokens collapse to ui-content-exit-fade. Directional motion is neutralized; opacity transitions still run because they communicate state without simulating motion.

Per-instance overrides win against the global reduced-motion fallback. If you need different motion under reduced motion for a specific panel, scope the override yourself with @media (prefers-reduced-motion: reduce).

FAQ

The panel does not appear. Check that triggerRef.current resolves to a DOM element before open flips to true. FloatingPanel measures against triggerRef.current on first paint; if the trigger has not mounted, no position resolves and the panel stays hidden.

The panel vanishes when I scroll. That is anchor tracking, not a bug. The panel re-measures against the trigger on every scroll and resize; once the trigger leaves the viewport (or the scrollable ancestor it lives in) the panel sets data-anchor-hidden and stops painting, because a clamped position detached from its anchor reads as a stray box floating over unrelated content. It stays mounted and focusable, and paints again as soon as the anchor scrolls back in. Close the panel on scroll in the wrapping primitive if you want it gone for good.

My custom transform animation is not anchored. Set transform-origin: var(--ui-content-transform-origin) inside your @keyframes rule. FloatingPanel writes the origin to the element on every measure based on the resolved side and align.

useFloatingPanelContext() throws. The hook only works inside a rendered FloatingPanel. When the panel is closed, no provider mounts. Read the context from a child component rendered within <FloatingPanel> children, not from the wrapping primitive.

The exit animation never finishes. FloatingPanel waits for animationend and falls back to exitFallbackMs (default 1000). If you raise --ui-content-exit-duration past 500ms, raise exitFallbackMs to at least 2× the new value.

Source

Install via CLI: pnpm exec dgadd add ui/floating-panel.

Highlighted source loads after this disclosure opens. Browse the source repository.

Floating Panel

Installation

Usage

Examples

Custom menu

Edge collision

API Reference

FloatingPanel

useFloatingPanelContext

Data attributes

CSS variables

Accessibility

Notes

Headless and Controlled

Positioning

CSS Custom Properties

Anchor Tracking

Style Merging

Accessibility

Context

CSS variables

Reduced motion

FAQ

Source

View component source (14 files)