or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-positioning.mdfocus-management.mdindex.mdinteraction-hooks.mdlayout-components.mdlist-navigation.mdpositioning-middleware.mdtransitions.mdtree-context.md
tile.json

tessl/npm-floating-ui--react

React library for creating accessible floating UI elements like tooltips, popovers, and dropdowns with advanced positioning

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@floating-ui/react@0.27.x

To install, run

npx @tessl/cli install tessl/npm-floating-ui--react@0.27.0

index.mddocs/

Floating UI React

Floating UI for React is a comprehensive library for creating accessible floating UI elements such as tooltips, popovers, dropdowns, and menus with advanced positioning and collision detection. It provides hooks and components for composing accessible interactions, handles anchor positioning by automatically keeping floating elements aligned with their reference elements while avoiding viewport collisions, and includes sophisticated user interaction patterns with keyboard navigation, focus management, and ARIA compliance.

Package Information

  • Package Name: @floating-ui/react
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @floating-ui/react

Core Imports

import { 
  useFloating, 
  useInteractions,
  useClick,
  useHover,
  useFocus,
  useDismiss,
  useRole,
  useTypeahead,
  useListNavigation,
  useMergeRefs,
  useId,
  FloatingFocusManager,
  FloatingPortal
} from '@floating-ui/react';

For CommonJS:

const { 
  useFloating, 
  useInteractions,
  useClick,
  useHover,
  useFocus,
  useDismiss,
  useRole,
  useTypeahead,
  useListNavigation,
  useMergeRefs,
  useId,
  FloatingFocusManager,
  FloatingPortal
} = require('@floating-ui/react');

Basic Usage

import {
  useFloating,
  useInteractions,
  useClick,
  useDismiss,
  useRole,
  FloatingFocusManager,
  FloatingPortal,
  offset,
  flip,
  shift
} from '@floating-ui/react';
import { useState } from 'react';

function Tooltip() {
  const [isOpen, setIsOpen] = useState(false);

  const { refs, floatingStyles, context } = useFloating({
    open: isOpen,
    onOpenChange: setIsOpen,
    middleware: [offset(10), flip(), shift()],
  });

  const click = useClick(context);
  const dismiss = useDismiss(context);
  const role = useRole(context);

  const { getReferenceProps, getFloatingProps } = useInteractions([
    click,
    dismiss,
    role,
  ]);

  return (
    <>
      <button ref={refs.setReference} {...getReferenceProps()}>
        Reference element
      </button>
      {isOpen && (
        <FloatingPortal>
          <div
            ref={refs.setFloating}
            style={floatingStyles}
            {...getFloatingProps()}
          >
            Tooltip content
          </div>
        </FloatingPortal>
      )}
    </>
  );
}

Architecture

Floating UI React is built around several key systems:

  • Positioning System: Core useFloating hook with middleware for collision detection and positioning
  • Interaction System: Composable hooks (useClick, useHover, etc.) merged via useInteractions
  • Focus Management: Comprehensive focus trapping and restoration via FloatingFocusManager
  • Component System: Layout components (FloatingPortal, FloatingOverlay) and specialized components
  • Tree System: Context for nested floating elements via FloatingTree and related hooks
  • Accessibility System: Built-in ARIA roles, keyboard navigation, and screen reader support

Capabilities

Core Positioning

Essential hooks for creating and positioning floating elements with collision detection and automatic updates.

function useFloating<RT extends ReferenceType = ReferenceType>(
  options?: UseFloatingOptions<RT>
): UseFloatingReturn<RT>;

interface UseFloatingReturn<RT extends ReferenceType = ReferenceType> {
  x: number;
  y: number;
  strategy: Strategy;
  placement: Placement;
  middlewareData: MiddlewareData;
  isPositioned: boolean;
  context: FloatingContext<RT>;
  refs: ExtendedRefs<RT>;
  elements: ExtendedElements<RT>;
  update(): void;
}

Core Positioning

Interaction Hooks

Composable hooks for handling user interactions like clicks, hovers, focus, and dismissal with floating elements.

function useInteractions(
  propsList?: Array<ElementProps | void>
): UseInteractionsReturn;

interface UseInteractionsReturn {
  getReferenceProps: (userProps?: React.HTMLProps<Element>) => Record<string, unknown>;
  getFloatingProps: (userProps?: React.HTMLProps<HTMLElement>) => Record<string, unknown>;
  getItemProps: (userProps?: React.HTMLProps<HTMLElement> & ExtendedUserProps) => Record<string, unknown>;
}

Interaction Hooks

Focus Management

Comprehensive focus management system for accessible floating elements with modal behavior, focus trapping, and restoration.

interface FloatingFocusManagerProps {
  children: React.JSX.Element;
  context: FloatingRootContext;
  disabled?: boolean;
  order?: Array<'reference' | 'floating' | 'content'>;
  initialFocus?: number | React.MutableRefObject<HTMLElement | null>;
  guards?: boolean;
  returnFocus?: boolean | React.MutableRefObject<HTMLElement | null>;
  restoreFocus?: boolean;
  modal?: boolean;
  visuallyHiddenDismiss?: boolean | string;
  closeOnFocusOut?: boolean;
  outsideElementsInert?: boolean;
}

Focus Management

List Navigation & Composite Widgets

System for creating accessible lists, menus, and composite widgets with keyboard navigation and proper ARIA support.

function useListNavigation(
  context: FloatingRootContext,
  props: UseListNavigationProps
): ElementProps;

interface UseListNavigationProps {
  listRef: React.MutableRefObject<Array<HTMLElement | null>>;
  activeIndex: number | null;
  onNavigate?: (activeIndex: number | null) => void;
  enabled?: boolean;
  orientation?: 'vertical' | 'horizontal' | 'both';
  loop?: boolean;
  nested?: boolean;
  focusItemOnOpen?: boolean | 'auto';
  focusItemOnHover?: boolean;
}

List Navigation

Layout Components

Essential components for controlling floating element layout, portaling, overlays, and visual presentation.

interface FloatingPortalProps {
  children?: React.ReactNode;
  id?: string;
  root?: HTMLElement | ShadowRoot | null | React.MutableRefObject<HTMLElement | ShadowRoot | null>;
  preserveTabOrder?: boolean;
}

interface FloatingOverlayProps {
  lockScroll?: boolean;
}

Layout Components

Tree Context & Coordination

System for managing nested floating elements and coordinating behavior across multiple related floating UIs.

interface FloatingTreeProps {
  children?: React.ReactNode;
}

function useFloatingTree(): FloatingTreeType | null;
function useFloatingNodeId(): string | undefined;
function useFloatingParentNodeId(): string | null;

Tree Context

Positioning Middleware

Re-exported positioning middleware from @floating-ui/react-dom for collision detection, placement optimization, and visual enhancements.

function offset(value?: OffsetOptions): Middleware;
function flip(options?: FlipOptions): Middleware;
function shift(options?: ShiftOptions): Middleware;
function arrow(options: ArrowOptions): Middleware;
function autoPlacement(options?: AutoPlacementOptions): Middleware;
function hide(options?: HideOptions): Middleware;
function size(options?: SizeOptions): Middleware;

Positioning Middleware

CSS Transitions

Smooth animation support for floating element enter/exit transitions with status tracking and pre-configured style management.

function useTransitionStatus(
  context: FloatingContext,
  props?: UseTransitionStatusProps
): {
  isMounted: boolean;
  status: 'unmounted' | 'initial' | 'open' | 'close';
};

function useTransitionStyles(
  context: FloatingContext,
  props?: UseTransitionStylesProps
): {
  isMounted: boolean;
  styles: Record<string, React.CSSProperties>;
};

CSS Transitions

Common Types

type ReferenceType = Element | VirtualElement;

type OpenChangeReason =
  | 'outside-press'
  | 'escape-key'
  | 'ancestor-scroll'
  | 'reference-press'
  | 'click'
  | 'hover'
  | 'focus'
  | 'focus-out'
  | 'list-navigation'
  | 'safe-polygon';

type Delay = number | Partial<{open: number; close: number}>;

interface FloatingContext<RT extends ReferenceType = ReferenceType> {
  open: boolean;
  onOpenChange(open: boolean, event?: Event, reason?: OpenChangeReason): void;
  x: number;
  y: number;
  strategy: Strategy;
  placement: Placement;
  middlewareData: MiddlewareData;
  isPositioned: boolean;
  elements: ExtendedElements<RT>;
  refs: ExtendedRefs<RT>;
  events: FloatingEvents;
  dataRef: React.MutableRefObject<ContextData>;
  nodeId: string | undefined;
  floatingId: string | undefined;
}

interface FloatingRootContext<RT extends ReferenceType = ReferenceType> {
  open: boolean;
  onOpenChange: (open: boolean, event?: Event, reason?: OpenChangeReason) => void;
  elements: {
    domReference: Element | null;
    reference: RT | null;
    floating: HTMLElement | null;
  };
  events: FloatingEvents;
  dataRef: React.MutableRefObject<ContextData>;
  floatingId: string | undefined;
  refs: {
    setPositionReference(node: ReferenceType | null): void;
  };
}

interface ElementProps {
  reference?: React.HTMLProps<Element>;
  floating?: React.HTMLProps<HTMLElement>;
  item?: React.HTMLProps<HTMLElement> | ((props: ExtendedUserProps) => React.HTMLProps<HTMLElement>);
}

interface ExtendedUserProps {
  active?: boolean;
  selected?: boolean;
}

Deprecated Exports

The following functions are deprecated and should not be used in new code:

/**
 * @deprecated Use positioning middleware instead
 */
function inner(options: InnerOptions): Middleware;

/**
 * @deprecated Use positioning middleware instead
 */
function useInnerOffset(
  context: FloatingContext, 
  options: UseInnerOffsetOptions
): ElementProps;