Fast & Versatile Positioning Library – Floating UI

Preview:

Description:

A great alternative to the Popper.js library.

Floating UI is a blazing-fast, feature-rich positioning library for positioning any type of “floating” elements (like tooltips, popovers, dropdowns) to a given reference element.

Key Features:

• Auto placement.
• Supports virtual elements.
• Auto flips floating elements to prevent overflow.
• Compatible with React.

Basic Usage:

1. Install and import the Floating UI.

# Yarn
$ yarn add @floating-ui/dom
# NPM
$ npm i @floating-ui/dom

import {computePosition} from 'https://cdn.jsdelivr.net/npm/@floating-ui/[email protected]/+esm';

2. Or load the Floating UI from a CDN.

<script type="module">
  import * as FloatingUIDOM from 'https://cdn.skypack.dev/@floating-ui/dom@versionHere';
</script>

// OR
<script src="https://cdn.jsdelivr.net/npm/@floating-ui/[email protected]"></script>
<script src="https://cdn.jsdelivr.net/npm/@floating-ui/[email protected]"></script>

3. Compute the necessary coordinates to position the floating element next to a given reference element.

<button id="button">My button</button>
<div id="tooltip">My tooltip</div>

const button = document.querySelector('#button');
const tooltip = document.querySelector('#tooltip');
computePosition(button, tooltip).then(({x, y}) => {
  Object.assign(tooltip.style, {
    left: `${x}px`,
    top: `${y}px`,
  });
});

4. Possible options for the computePosition.

computePosition(referenceEl, floatingEl, {
  // top', 'top-start', 'top-end', 'right'
  // 'right-start', 'right-end'
  // 'bottom', 'bottom-start', 'bottom-end'
  // 'left', 'left-start', 'left-end';
  placement: 'bottom', 
  // 'absolute' | 'fixed'
  strategy: 'default'
  // autoPlacement
  // arrow
  // flip
  // hide
  // offset
  // shift
  // size
  // or a custom function
  middleware: [],
});

5. Modify the positioning coordinates or provide useful data using the middleware option.

// offset in px
import {computePosition, offset} from '@floating-ui/dom';
computePosition(referenceEl, floatingEl, {
  middleware: [offset(10)],
});

// move the floating element along the specified axes
import {computePosition, shift} from '@floating-ui/dom';
computePosition(referenceEl, floatingEl, {
  middleware: [shift()],
});

// changes the placement of the floating element to the opposite one by default
import {computePosition, flip} from '@floating-ui/dom';
computePosition(referenceEl, floatingEl, {
  middleware: [flip()],
});

// auto placement
import {computePosition, autoPlacement} from '@floating-ui/dom';
computePosition(referenceEl, floatingEl, {
  middleware: [autoPlacement()],
});

// hide the floating element in applicable situations
import {computePosition, hide} from '@floating-ui/dom';
computePosition(referenceEl, floatingEl, {
  middleware: [hide()],
}).then(({middlewareData}) => {
  const {referenceHidden} = middlewareData.hide;
  Object.assign(floatingEl.style, {
    visibility: referenceHidden ? 'hidden' : 'visible',
  });
});

// improved positioning for inline reference elements that span over multiple lines, such as hyperlinks or range selections
import {computePosition, inline} from '@floating-ui/dom';
computePosition(referenceEl, floatingEl, {
  middleware: [inline()],
});

// position an inner element of the floating element (usually a triangle or caret) so that it is centered to the reference element
<div id="tooltip">
  Tooltip text
  <div id="arrow"></div>
</div>
import {computePosition, arrow} from '@floating-ui/dom';
const arrowEl = document.querySelector('#arrow');
computePosition(referenceEl, floatingEl, {
  middleware: [
    arrow({
      element: arrowEl,
    }),
  ],
}).then(({middlewareData}) => {
  const {x, y} = middlewareData.arrow;
  Object.assign(arrowEl.style, {
    left: x != null ? `${x}px` : '',
    top: y != null ? `${y}px` : '',
  });
});

// change the size of the floating element
import {computePosition, size} from '@floating-ui/dom';
computePosition(referenceEl, floatingEl, {
  middleware: [
    size({
      apply({width, height, reference, floating}) {
        // Do things with the data, e.g.
        Object.assign(floatingEl.style, {
          maxWidth: `${width}px`,
          maxHeight: `${height}px`,
        });
      },
    }),
  ],
});

6. Automatically update the position of the floating element when required.

import {computePosition, autoUpdate} from '@floating-ui/dom';
async function update() {
  const {x, y} = await computePosition(referenceEl, floatingEl);
}
const cleanup = autoUpdate(referenceEl, floatingEl, update);

7. Compute the overflow offsets of either the reference or floating element relative to any clipping boundaries.

import {detectOverflow} from '@floating-ui/dom';
const middleware = {
  name: 'middleware',
  async fn(middlewareArguments) {
    const overflow = await detectOverflow(middlewareArguments);
    return {};
  },
};

Changelog:

v2.1.4 (06/28/2025)

• bugfix

v1.7.1 (06/02/2025)

• Update dependencies: @floating-ui/[email protected]

v1.7.0 (05/02/2025)

• feat(flip): add “alignment” string value for crossAxis option. This value determines if cross axis overflow checking is restricted to the alignment of the placement only. This prevents fallbackPlacements/fallbackAxisSideDirection from too eagerly changing to the perpendicular side (thereby preferring shift() if overflow is detected along the cross axis, even if shift() is placed after flip() in the middleware array).
• fix: correct position when document scrollbar is on left side with fixed strategy
• Update dependencies: @floating-ui/[email protected]

v1.6.13 (01/07/2025)

• bugfixes

v1.6.12 (10/30/2024)

• bugfixes

v1.6.11 (09/15/2024)

• update dependencies

v1.6.10 (08/07/2024)

• update dependencies

v1.6.9 (08/05/2024)

• update dependencies

v1.6.8 (07/22/2024)

• update dependencies

v1.6.7 (06/30/2024)

• bugfixes

v1.6.6 (06/24/2024)

• bugfixes
• refactor: improve types and internal codebase consistency.
• update dependency

v1.6.5 (05/04/2024)

• bugfixes

v1.6.4 (04/28/2024)

• bugfixes
• perf(autoUpdate): reduce layoutShift update checks while reference is clipped from view

v1.6.2 (02/11/2024)

• bugfix

v1.6.1 (01/28/2024)

• update dependencies

v1.6.0 (01/25/2024)

• bugfix

v1.5.4 (01/06/2024)

• chore: exports .d.mts types
• refactor: avoid $ appearing in rects dimensions
• Updated dependencies

v1.5.3 (09/14/2023)

• Bugfix

v1.5.2 (09/11/2023)

• Bugfix

v1.5.1 (07/30/2023)

• Bugfix

v1.5.0 (07/28/2023)

• Split utils into @floating-ui/utils package (@floating-ui/utils/dom import

v1.4.5 (07/13/2023)

• bugfix

v1.4.4 (07/06/2023)

• bugfix

v1.4.3 (06/29/2023)

• bugfix

v1.4.3 (06/29/2023)

• bugfix

v1.4.2 (06/21/2023)

• bugfix

v1.4.1 (06/19/2023)

• bugfix

v1.3.1 (06/18/2023)

• bugfix

v1.3.0 (06/12/2023)

• feat: allow function types for all middleware options, including detectOverflow, to allow derivation from state
• refactor(types): exported middleware Options types
• fix(arrow): ensure large padding option value does not cause incorrect centering

05/29/2023

• v1.2.9: bugfixes

05/14/2023

• v1.2.8: bugfixes

04/27/2023

• v1.2.7: bugfixes

04/07/2023

• v1.2.6: bugfixes

03/20/2023

• v1.2.5: bugfixes

03/13/2023

• v1.2.4: bugfixes

03/01/2023

• v1.2.3: bugfixes

02/12/2023

• v1.2.1: bugfixes

02/05/2023

• v1.2.0: feat(platform): add ability to polyfill offsetParent access (in a pure way) to fix a platform gap where the incorrect value is returned inside shadow DOM; feat(detectOverflow): accept virtual Rect boundaries.

01/28/2023

• v1.1.1: bugfixes

12/27/2022

• v1.1.0: bugfixes

12/16/2022

• v1.0.12: bugfixes

12/12/2022

• v1.0.10: bugfixes; performance improvements

12/07/2022

• v1.0.9: fix: correctly handle parent scale transforms when detecting clipping

12/06/2022

• v1.0.8: Bugfix

11/24/2022

• v1.0.7: Bugfix

11/16/2022

• v1.0.5: Bugfix

10/30/2022

• v1.0.4: fix(autoUpdate): add event listeners to a VirtualElement’s contextElement if present

10/19/2022

• v1.0.3: Bugfixes

09/19/2022

• v1.0.2: Performance Improvements

08/09/2022

• v1.0.1

07/19/2022

• v1.0.0

06/12/2022

• v0.5.3: Bugfix

05/28/2022

• v0.5.2: Bugfix

05/19/2022

• v0.5.1: Bugfix