NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm · #488 most downloaded on npm
Floating UI for React DOM
Last release 2 months ago
11 Jul 2026
Release timing varies
gaps range from 3 weeks to 9 months
Most releases are documented
notes for 38 of 52 stable releases
Nothing withdrawn
no release was ever pulled
5 years old
52 releases · first in 2021
One column per quarter.
fix: support explicit undefined for optional properties with exactOptionalPropertyTypes
undefined for optional properties with exactOptionalPropertyTypes@floating-ui/dom@1.8.0fix(react): avoid duplicate options key warning in reactive middleware wrappers
options key warning in reactive middleware wrappers@floating-ui/dom@1.7.6Update dependencies: @floating-ui/dom@1.7.5
@floating-ui/dom@1.7.5Update dependencies: @floating-ui/dom@1.7.4
@floating-ui/dom@1.7.4Update dependencies: @floating-ui/dom@1.7.3
@floating-ui/dom@1.7.3Update dependencies: @floating-ui/dom@1.7.2
@floating-ui/dom@1.7.2fix(useFloating): correct transform default doc (@default true instead of @default false)
transform default doc (@default true instead of @default false)fix(useFloating): avoid setting isPositioned to true when open is false
isPositioned to true when open is falserefactor: improve types and internal codebase consistency. All documented types are now exported.
feat: support dependency array as a second argument of all middleware. This ensures stateful options can be kept reactive when making them derived (pa
const [value, setValue] = React.useState(0);
const offset1 = offset(value); // reactive
const offset2 = offset(() => value); // NOT reactive
const offset3 = offset(() => value, [value]); // reactive
This also includes size's apply function:
size(
{
apply() {
value; // reactive
},
},
[value],
);
fix(types): replace React_2 with React in generated .d.ts files
React_2 with React in generated .d.ts filesUpdate dependencies: @floating-ui/dom@1.6.1
@floating-ui/dom@1.6.1Update dependencies: @floating-ui/dom@1.6.0
@floating-ui/dom@1.6.0d3a773b: fix: make whileElementsMounted reactive with respect to changing from a function to undefined
whileElementsMounted reactive with respect to changing from a function to undefinedwhileElementsMounted reactive with respect from changing from a function to undefined4c04669: chore: export .d.mts types, solves #2472
9d22d831: fix: package type import
c1965f65: refactor: minor jsdoc/type improvements
fix(types): import types from dom instead of core
dom instead of core (#2513)fix: adjust types for new function options feature in core/dom 1.3.0
core/dom 1.3.0 (#2359)undefined for optional properties with exactOptionalPropertyTypes@floating-ui/dom@1.8.0, @floating-ui/utils@0.2.12This release aims to simplify the API and remove some deprecated properties. If you've been using the refs.set* functions since their addition in Janu…
This release aims to simplify the API and remove some deprecated properties. If you've been using the refs.set* functions since their addition in January (1.2.0), then you can freely upgrade without changing any of your code.
Default x and y coordinates to 0 instead of null (#2300)
isPositioned lets you know if the floating element has been positioned.
Remove deprecated top-level reference and floating ref setters (#2300)
These are in the refs object:
reference -> refs.setReferencefloating -> refs.setFloatingwhileElementsMounted type requires cleanup function (#2300)
feat: floatingStyles object (#2300)
Pre-configured positioning styles for the majority of cases:
const {refs, floatingStyles} = useFloating();
return <div ref={refs.setFloating} style={floatingStyles} />;
feat: external element synchronization in the hook (#2300)
Avoid using layout effects:
const {refs} = useFloating({
elements: {
// Either can be specified optionally
reference: referenceElement,
floating: floatingElement,
},
});
// refs.setReference / refs.setFloating can be mix and matched
null for arrow's element option (#2300)vue-demi package (see Deprecation Warning), ending support for Vue 2 and Vue <3.3.0feat: allow function types for all middleware options, including detectOverflow, to allow derivation from state
feat: allow function types for all middleware options, including detectOverflow, to allow derivation from state (#2359)
// Options
shift({mainAxis: true});
// Derived from state
shift((state) => ({mainAxis: state.rects.reference.width > 10}));
refactor(types): exported middleware Options types (#2359)
Options objects now include DetectOverflowOptions in them, and are auto-Partial where necessary. The types do not include the function type in them.feat: allow function types for all middleware options, including detectOverflow, to allow derivation from state (#2359)
// Options
shift({mainAxis: true});
// Derived from state
shift((state) => ({mainAxis: state.rects.reference.width > 10}));
refactor(types): exported middleware Options types (#2359)
Options objects now include DetectOverflowOptions in them, and are auto-Partial where necessary. The types do not include the function type in them.padding option value does not cause incorrect centering (#2360)platform object to be passed to the useFloating hook (#2176)fix(types): re-export middleware options types (#2175)
fix(types): add @deprecation notice to non-ref nested element setters (#2175)
fix(arrow): correctly take into account floating element border for arrows
border for <svg> arrows (#2195)fix(getClippingRect): prevent fixed ancestors from creating a clipping ancestor
fix(getClippingRect): prevent fixed ancestors from creating a clipping ancestor (#2170)
fix(types): re-export middleware options types (#2175)
MiddlewareArguments in favor of MiddlewareState type (#2175)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
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. (#2160)
This was previously done internally a while ago (1.0.1) but reportedly causes a performance issue in certain scenarios, meaning it cannot be a default. This allows the polyfill to be conditionally enabled by libraries. The polyfill and its usage is available here, which ideally would be made into its own package (that can be iterated on and potentially improved perf-wise).
feat(detectOverflow): accept virtual Rect boundaries (#2161)
platform object now has all methods non-optional with Required<Platform> (#2166)feat(autoPlacement): crossAxis option (#2159)
By default, aligned placements like top-start/top-end use a "fallback" strategy for the crossAxis to ensure different axes' placements can be chosen, and to keep the preferred alignment as much as possible.
However, if you only have placements along one axis you can now use a "most space" strategy for the alignment as well, e.g.:
autoPlacement({
allowedPlacements: [
'top-start',
'top-end',
'bottom-start',
'bottom-end'
],
crossAxis: true,
});
feat(detectOverflow): accept virtual Rect boundaries (#2161)
fix(size): consider case where shift() is in the middleware array before size() for center aligned placements (#2163)
fix(autoPlacement): prevent resetting placement unexpectedly to opposite alignment when it overflows on all sides (#2159)
fix(flip): when no placements fit, but before fallbackStrategy phase, if multiple placements fit on the mainAxis of overflow, choose the placement that fits best on the main crossAxis side of overflow (#2163)
fix(autoPlacement): general algorithm improvements (#2159)
fix(size): general algorithm improvements (#2163)
feat: add element setters to refs object (#2101)
const {refs} = useFloating();
<div ref={refs.setReference} />
<div ref={refs.setFloating} />
These replace the reference and floating callback refs (which are now aliases) by being more explicit and less confusing regarding how refs are updated.
The refs object contains:
{
reference: MutableRefObject,
floating: MutableRefObject,
setReference: (node) => void,
setFloating: (node) => void,
}
feat: return elements object from hook (#2101)
If you need to read the elements during render, where refs are not suitable, these contain the elements rather than refs.
Update dependencies: @floating-ui/utils@0.2.5
@floating-ui/utils@0.2.5fix: ensure MaybeReadonlyRefOrGetter works in earlier versions of Vue
MaybeReadonlyRefOrGetter works in earlier versions of VuemainAxis overflow check first once in fallback phase (#2151)fix(types): allow SVGElement as the arrow element (#2146)
fix(arrow): re-allow SVGElements to be measured (#2146)
fix: re-allow unstable ref callbacks (prevent infinite loop) (#2087)
Since v1.0.0 you didn't need to memoize the callback ref (although is recommended), but in v1.1.0 this caused an infinite loop again:
ref={node => floating(node)}
perf: optimize calling floating and reference callback refs directly in render (#2087)
The docs recommended to use effects to synchronize external elements, but now there's an optimization that allows you to call either during render without needing an effect:
function App({externalNode}) {
const {reference} = useFloating();
// Works and is optimized, no effect needed
reference(externalNode);
}
feat: support MaybeReadonlyRefOrGetter in useFloating
MaybeReadonlyRefOrGetter in useFloating@floating-ui/utils@0.2.4feat(flip): fallbackAxisSideDirection option (#2082)
This option adds the ability to compute placements on the opposite axis of the preferred placement without needing to use an explicit fallbackPlacements list, meaning you no longer need to manage a custom map of fallbackPlacements and instead use this option to leverage automatic computing of the array.
This option determines whether to allow fallback to the opposite axis if no placements along the preferred placement axis fit, and if so, which side direction along that axis to choose. If necessary, it will fallback to the other direction.
'none' signals that no fallback to the opposite axis should take place. (default)'start' represents 'top' or 'left'.'end' represents 'bottom' or 'right'.Note: In RTL writing direction, the x-axis directions are reversed.
For instance, by default, if the initial placement is set to 'right', then the placements to try (in order) are:
['right', 'left']
On a narrow viewport, it's possible or even likely that neither of these will fit.
By specifying a string other than 'none', you allow placements along the opposite axis of the initial placement to be tried. The direction determines which side of placement is tried first:
flip({
fallbackAxisSideDirection: 'start',
});
The above results in: ['right', 'left', 'top', 'bottom'].
flip({
fallbackAxisSideDirection: 'end',
});
The above results in: ['right', 'left', 'bottom', 'top'].
As an example, if you'd like a tooltip that has a placement of 'right' to be placed on top on mobile (assuming it doesn't fit), then you'd use 'start'. For an interactive popover, you likely want to use 'end' so it's placed on the bottom, closer to the user's fingers.
shiftIf shift() is in use in the middleware array, you may desire to disable crossAxis overflow checking, which will allow shift() to perform its work without falling back to the opposite axis (therefore preserving the original axis as best as possible):
const middleware = [
flip({
fallbackAxisSideDirection: 'start',
crossAxis: false,
}),
shift(),
];
This will depend on the desired positioning you want to achieve, e.g. if the placement has an explicit alignment specified or not.
feat: add open option and isPositioned property to wait for the position to be ready. (#2001)
isPositioned allows you to call .scrollIntoView() or .focus() on an element in an effect without causing unwanted scrolling.
const {isPositioned} = useFloating();
This works identically to x === null, but now has the ability to also reset if it doesn't get unmounted based on some state:
const [open, setOpen] = useState(false);
const {isPositioned} = useFloating({
// `isPositioned` is synchronized to this state/value, but
// when it changes to `true`, it will wait for the position,
// unlike when checking `open` directly.
open
});
React.useLayoutEffect(() => {
if (isPositioned) {
element.focus();
element.scrollIntoView();
}
}, [isPositioned]);
This means it will also work if the reference element moved from the first position after the floating element had been positioned for the first time, unlike x === null, making it as reliable as the rAF technique.
For now, null remains as the original value of x and y only for SSR purposes, where the floating element is open already without a client interaction required, which can help with unmounting animations, since isPositioned doesn't wait.
<div
style={{
position: strategy,
top: y ?? 0,
left: x ?? 0,
visibility: x === null ? 'hidden' : 'visible',
}}
/>
fix: support cross-document anchoring, where if floating element is in a higher-level window than the reference element, the positioning takes this into account (i.e. reference element is inside an iframe, but the floating element isn't) (#2043)
Bumping minor version because if you were adding external code/custom middleware to add support yourself, it will break with this update as it's no longer necessary.
refactor(getScale): handle unknowns (#2054)
fix(getDimensions): use computed width/height if possible (#2056)
If using box-sizing: border-box (recommended default by most CSS resets, and this lib), then the floating rect will now always contain fractional values. When using size to set the width of the floating element, it will no longer be truncated unexpectedly (e.g. adding ... ellipsis overflow).
fix(isOverflowElement): check for overflow: clip value (#2070)
fix: package.json dependency metadata
middleware option for conditionals (#1954)Shadow DOM fixes
fix: incorrect position when starting offset parent element is nested inside shadow DOM (#1827)
fix: add composedOffsetParent internal polyfill for shadow DOM offsetParents (#1835)
SideObject for detectOverflow padding (#1846)Default x and y coordinates to 0 instead of null
Default x and y coordinates to 0 instead of null (#2300)
isPositioned lets you know if the floating element has been positioned.
feat: floatingStyles object (#2300)
Pre-configured positioning styles for the majority of cases:
const {floatingStyles} = useFloating(reference, floating);
<div ref="floating" :style="floatingStyles" />
@floating-ui/core bumped to 1.0.0 (#1796)
UMD package files now have .umd in the filename (#1796)
fix: allow unstable inline ref callbacks (#1796)
fix: check name for middleware array comparisons (#1796)
use-isomorphic-layout-effect from installed deps (#1796)limitShift offset function option now gets whole MiddlewareArguments object spread in to match other APIs (#1796)apply function now has await before it to allow async updates (#1796)TS typedefs are now generated as "strict"
TS typedefs are now generated as "strict"
feat: inner middleware — the floating element is anchored such that an inner element inside of it sits on top of/is anchored to the reference element.
feat: inner middleware — the floating element is anchored such that an inner element inside of it sits on top of/is anchored to the reference element. (#1758)
This works along the y-axis and simulaneously limits the max-height of the floating element.
feat: useInnerOffset interaction hook — allows the height of the floating element to expand on wheel event by changing the offset that inner uses to anchor the inner element (#1758)
FloatingFocusManager. useListNavgation and useDismiss no longer return focus, bypassing issues with unmounting animations. (#1765)fix(useDismiss): outsidePointerDown now uses real pointerdown instead of mousedown (#1765)
Before it required an "intentional" dismiss on touch devices, but now, the user can dismiss while attempting to scroll away
fix(useHover): prevent SVG reference element from failing to apply pointer-events auto styles (#1794)
fix(useClick): pointerDown now uses mousedown instead of pointerdown. This reduces unintentional clicks while touching the screen to scroll, or focus being moved to focusable items inside a floating element unintentionally when tapping the reference element. (#1765)
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
180d1ad: fix: devtools controller emits event once the selected element is removed
3d0368e: feat!: introduce serialized data as an array
/react pathopen option and isPositioned return value (#2083)a6c72f50: fix(getOverflowAncestors): avoid traversing into iframes for clipping detection
cb48d956: fix(dom): traverse into iframe parents when finding overflow ancestors
Export getContainingBlock utility from /dom
Export getContainingBlock utility from /dom (#2474)
fix(types): resolution when using moduleResolution: "NodeNext" (#2473)
## New Features - Initial release
Your coding agent can read these notes before it upgrades. Set up the MCP server →