or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-middleware.mdbasic-middleware.mdcore-positioning.mdindex.mdoverflow-detection.md
tile.json

tessl/npm-floating-ui--core

Platform-agnostic core positioning engine for floating UI elements like tooltips, popovers, and dropdowns.

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

To install, run

npx @tessl/cli install tessl/npm-floating-ui--core@1.7.0

index.mddocs/

@floating-ui/core

@floating-ui/core provides the platform-agnostic core positioning engine for floating UI elements such as tooltips, popovers, dropdowns, and menus. It exposes the main computePosition function that calculates optimal placement coordinates while avoiding viewport collisions and maintaining anchor relationships. The library includes a comprehensive middleware system for advanced positioning behaviors.

Package Information

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

Core Imports

import { computePosition } from "@floating-ui/core";

For all middleware and types:

import { 
  computePosition, 
  offset, 
  flip, 
  shift, 
  limitShift,
  arrow,
  autoPlacement,
  hide,
  inline,
  size,
  detectOverflow,
  rectToClientRect, // Deprecated
  type ComputePositionConfig,
  type ComputePositionReturn,
  type Middleware
} from "@floating-ui/core";

For CommonJS:

const { computePosition, offset, flip, shift } = require("@floating-ui/core");

Basic Usage

import { computePosition, offset, flip, shift } from "@floating-ui/core";

// Basic positioning with middleware
const config = {
  placement: "bottom",
  middleware: [
    offset(6),
    flip(),
    shift({ padding: 8 })
  ],
  platform: myPlatform // Platform interface implementation required
};

const result = await computePosition(referenceElement, floatingElement, config);

// Use the computed coordinates
console.log(result.x, result.y); // Position coordinates
console.log(result.placement); // Final placement used

Architecture

@floating-ui/core is built around several key components:

  • Core Engine: computePosition function that computes optimal coordinates for floating elements
  • Middleware System: Extensible pipeline of positioning behaviors that modify placement and provide data
  • Platform Interface: Abstraction layer requiring platform-specific implementations for DOM operations
  • Type System: Complete TypeScript integration with comprehensive type definitions
  • Overflow Detection: Advanced clipping boundary detection with configurable options

Capabilities

Core Positioning

Main positioning function that computes coordinates for floating elements relative to reference elements.

function computePosition(
  reference: unknown,
  floating: unknown,
  config: ComputePositionConfig
): Promise<ComputePositionReturn>;

interface ComputePositionConfig {
  platform: Platform;
  placement?: Placement;
  strategy?: Strategy;
  middleware?: Array<Middleware | null | undefined | false>;
}

interface ComputePositionReturn {
  x: number;
  y: number;
  placement: Placement;
  strategy: Strategy;
  middlewareData: MiddlewareData;
}

Core Positioning

Basic Middleware

Essential middleware for common positioning scenarios including offset, flip, and shift behaviors.

function offset(options?: OffsetOptions): Middleware;
function flip(options?: FlipOptions): Middleware;
function shift(options?: ShiftOptions): Middleware;
function limitShift(options?: LimitShiftOptions): { fn: (state: MiddlewareState) => Coords; options: any };

type OffsetOptions = number | {
  mainAxis?: number;
  crossAxis?: number;
  alignmentAxis?: number | null;
};

Basic Middleware

Advanced Middleware

Specialized middleware for complex positioning scenarios including auto-placement, arrow positioning, size constraints, and visibility detection.

function autoPlacement(options?: AutoPlacementOptions): Middleware;
function arrow(options: ArrowOptions): Middleware;
function size(options?: SizeOptions): Middleware;
function hide(options?: HideOptions): Middleware;
function inline(options?: InlineOptions): Middleware;

Advanced Middleware

Overflow Detection

Utility for detecting element overflow within clipping boundaries.

function detectOverflow(
  state: MiddlewareState,
  options?: DetectOverflowOptions
): Promise<SideObject>;

interface DetectOverflowOptions {
  boundary?: Boundary;
  rootBoundary?: RootBoundary;
  elementContext?: ElementContext;
  altBoundary?: boolean;
  padding?: Padding;
}

Overflow Detection

Core Types

// Platform interface for DOM operations
interface Platform {
  getElementRects(args: {
    reference: ReferenceElement;
    floating: FloatingElement;
    strategy: Strategy;
  }): Promise<ElementRects> | ElementRects;
  getClippingRect(args: {
    element: any;
    boundary: Boundary;
    rootBoundary: RootBoundary;
    strategy: Strategy;
  }): Promise<Rect> | Rect;
  getDimensions(element: any): Promise<Dimensions> | Dimensions;
  // Optional methods...
}

// Middleware interface
interface Middleware {
  name: string;
  options?: any;
  fn: (state: MiddlewareState) => Promise<MiddlewareReturn> | MiddlewareReturn;
}

interface MiddlewareState {
  x: number;
  y: number;
  initialPlacement: Placement;
  placement: Placement;
  strategy: Strategy;
  middlewareData: MiddlewareData;
  elements: Elements;
  rects: ElementRects;
  platform: Platform;
}

interface MiddlewareReturn {
  x?: number;
  y?: number;
  data?: { [key: string]: any };
  reset?: boolean | { placement?: Placement; rects?: boolean | ElementRects };
}

// Common utility types from @floating-ui/utils
type Placement = Side | `${Side}-${Alignment}`;
type Side = "top" | "right" | "bottom" | "left";
type Alignment = "start" | "end";
type Strategy = "absolute" | "fixed";
type Coords = { x: number; y: number };
type Dimensions = { width: number; height: number };
type Rect = Coords & Dimensions;
type SideObject = { top: number; right: number; bottom: number; left: number };
type ElementRects = { reference: Rect; floating: Rect };
type Padding = number | Partial<SideObject>;

Deprecated Exports

/**
 * Converts Rect to ClientRectObject format
 * @deprecated This export exists only for backwards compatibility. 
 * It will be removed in the next major version.
 */
function rectToClientRect(rect: Rect): ClientRectObject;