@vielzeug/floatit

Lightweight floating-element positioning for tooltips, dropdowns, popovers, and menus.

Floatit is a zero-dependency DOM positioning engine used by Vielzeug components and available as a standalone package. It gives you a small, composable API for computing and applying floating positions, plus middleware for offsetting, flipping, shifting, sizing, and auto-updating.

Installation

pnpm add @vielzeug/floatit
# npm install @vielzeug/floatit
# yarn add @vielzeug/floatit

Quick Start

import { autoUpdate, flip, offset, positionFloat, shift } from '@vielzeug/floatit';

const reference = document.querySelector('#trigger')!;
const floating = document.querySelector('#tooltip')!;

await positionFloat(reference, floating, {
  placement: 'top',
  middleware: [offset(8), flip(), shift({ padding: 6 })],
});

const cleanup = autoUpdate(reference, floating, () => {
  positionFloat(reference, floating, {
    placement: 'top',
    middleware: [offset(8), flip(), shift({ padding: 6 })],
  });
});

// later
cleanup();

Features

• ✅ positionFloat() — compute and apply left / top styles in one call
• ✅ computePosition() — low-level { x, y, placement } API when you want to control rendering yourself
• ✅ Composable middleware — offset, flip, shift, and size
• ✅ autoUpdate() — keeps floating UI aligned on scroll, resize, and element resizes
• ✅ Typed placement model — top, bottom-start, left-end, and related helpers
• ✅ Zero dependencies — pure DOM APIs only

API Summary

| Export | Description | |---|---| | positionFloat(reference, floating, options?) | Compute and apply the floating position | | computePosition(reference, floating, config?) | Return { x, y, placement } without mutating the DOM | | autoUpdate(reference, floating, update, options?) | Re-run positioning when layout conditions change | | offset(value) | Add distance between reference and floating element | | flip(options?) | Flip to the opposite side when the preferred side overflows | | shift(options?) | Clamp the floating element inside the viewport | | size(options?) | Provide available dimensions and resize hooks |

Usage Notes

• strategy is part of the public option types but is not currently applied internally; position from viewport coordinates (typically with position: fixed CSS).
• Middleware runs in order; the common chain is offset(), flip(), shift(), then size().
• Call the cleanup returned by autoUpdate() when the floating UI closes.
• Use autoUpdate(..., { observeFloating: false }) when observing floating-size changes would cause unnecessary update loops.
• Use computePosition() when you want to apply transforms or animations yourself.

Documentation

Full docs at vielzeug.dev/floatit

| | | |---|---| | Overview | Installation, quick start, and feature overview | | Usage Guide | Placement, middleware, and lifecycle patterns | | API Reference | Complete function signatures and types | | Examples | Tooltips, dropdowns, and framework recipes |

License

MIT © Helmuth Saatkamp — Part of the Vielzeug monorepo.