Floating UI

@floating-ui/react is the official React binding for Floating UI, the successor to Popper.js. It provides a low-level positioning hook, useFloating, alongside a full set of composable interaction hooks — useClick, useHover, useDismiss, useFocus, useRole, useListNavigation, and useTypeahead — that merge together via useInteractions to build accessible tooltips, popovers, dropdowns, select menus, and comboboxes.

Beyond raw positioning, the library solves the harder problems that come with floating UI: focus management, keyboard navigation, screen-reader semantics, portal rendering, nested floating trees for submenus, and safe-polygon hover-intent detection. It underpins a large share of the React ecosystem’s custom tooltip and popover implementations, from internal design systems to production component libraries.

What You Get

• useFloating hook for anchoring a floating element to a reference element with automatic placement, flip, shift, and size middleware
• A composable interaction system (useClick, useHover, useFocus, useDismiss, useRole, useListNavigation, useTypeahead) merged via useInteractions
• Accessible building-block components: FloatingFocusManager, FloatingPortal, FloatingArrow, FloatingOverlay, and FloatingTree for nested menus
• safePolygon for hover-intent detection between a reference and floating element, and FloatingDelayGroup for shared open/close delays across sibling triggers

Common Use Cases

• Building a custom tooltip component with accurate arrow positioning and collision detection
• Implementing an accessible dropdown or select menu with keyboard navigation and typeahead
• Creating nested context menus or submenus using FloatingTree without losing focus and dismiss coordination
• Adding a popover or combobox to a design system that needs to work inside scrollable or transformed containers

Under The Hood

Architecture - @floating-ui/react layers three concerns on top of the platform-agnostic @floating-ui/dom engine: positioning (useFloating in src/hooks/useFloating.ts wraps @floating-ui/react-dom’s useFloating and composes it with useFloatingRootContext.ts, which owns a shared FloatingContext object holding refs, position data, and interaction state), interaction composition (each of the hooks in src/hooks/ — useClick.ts, useHover.ts, useDismiss.ts, useRole.ts, useListNavigation.ts, useTypeahead.ts, useFocus.ts, useClientPoint.ts — returns a partial prop-getter object that useInteractions.ts merges into a single getReferenceProps/getFloatingProps/getItemProps pair), and accessible rendering (components in src/components/ — FloatingFocusManager.tsx for focus trapping, FloatingPortal.tsx for DOM portaling, FloatingTree.tsx/FocusGuard.tsx for nested-menu coordination via React context, and FloatingList.tsx for indexable item registries used by useListNavigation). The FloatingTree context is the key architectural device for correctness in nested UIs: submenus register as FloatingNode children so a dismiss or hover event on a child does not incorrectly close its ancestors.

Tech Stack - The package is TypeScript-first (TypeScript is 68.8% of the monorepo by bytes) and built with Rollup, emitting dual ESM/UMD bundles plus .d.ts and .d.mts type declarations distributed through package.json exports conditions for both the root API and a separate /utils subpath. It depends on @floating-ui/react-dom and @floating-ui/utils, both workspace-linked siblings in the pnpm monorepo, plus the small tabbable library for focus-order queries, and declares react/react-dom >=17 as peer dependencies so it stays framework-version-agnostic. Development uses Vite for the local test playground, Vitest (including a real-browser mode via vitest-browser-react) for unit tests, and Testing Library/user-event for interaction assertions; the whole repo is orchestrated with pnpm workspaces and Turborepo.

Code Quality - Test coverage is substantial: 22+ test files under packages/react/test/unit covering focus management, delay groups, node/tree registration, and each interaction hook, written with Testing Library idioms (render, fireEvent, userEvent) that exercise real DOM and focus behavior rather than shallow rendering. Source files are consistently typed with exported generic type parameters (e.g. useFloating<RT extends ReferenceType>), JSDoc comments link back to the public docs site (@see https://floating-ui.com/docs/useFloating), and naming is uniform across the hook/component split (useX for hooks, FloatingX for components). A shared ESLint config and tsconfig.base.json enforce consistency across all seven packages in the monorepo.

API Design - The API favors small, composable primitives over monolithic configuration objects: each interaction is its own hook returning prop-getter functions that useInteractions merges, so consumers opt into exactly the behaviors they need — a plain tooltip might use only useHover, useFocus, and useDismiss, while a combobox adds useListNavigation and useTypeahead. Getting started requires minimal boilerplate, since useFloating() alone returns refs and positioning styles, and the docs site plus in-source @see links keep the learning curve manageable despite the surface area. The one friction point is the number of hooks a complex component like a full combobox must wire together correctly, though FloatingTree and FloatingDelayGroup exist specifically to remove manual coordination for the hardest nested-UI cases.