floating-ui/floating-ui
@floating-ui/vue
Floating UI for Vue
Version:
1.1.11 (Mar 2026)
Deps:
vue-demi@>=0.13.0, @floating-ui/dom@^1.7.6, @floating-ui/utils@^0.2.11
Tags:
latest: 1.1.11 (Mar 2026)
References:
Docs
— API reference, guides
API Changes
This section documents version-specific API changes for
@floating-ui/vue
— prioritize the v1.0.0 major release and subsequent minor updates.
BREAKING:
x
and
y
coordinates now default to
0
instead of
null
since v1.0.0. Use
isPositioned
to check if layout is ready
source
NEW:
floatingStyles
— Returns a pre-configured
style
object for the floating element (position, top, left, transform) since v1.0.0
source
NEW:
MaybeReadonlyRefOrGetter
—
useFloating
options now support getters (e.g.,
() => props.placement
) and refs since v1.1.0
source
NEW:
isPositioned
— Boolean ref returned by
useFloating
that indicates if the floating element has been positioned since v0.2.0
source
NEW:
open
option — Optional boolean ref in
useFloating
to synchronize
isPositioned
with the element's open state since v0.2.0
source
IMPROVED:
ArrowOptions.element
— Widened type to
MaybeElement
to improve compatibility with Vue Template Refs since v1.0.2
source
NEW:
whileElementsMounted
— Preferred option for
useFloating
to handle the
autoUpdate
lifecycle automatically since v1.0.0
source
NEW:
update()
— Function returned by
useFloating
to manually trigger a position recalculation since v0.2.0
source
NEW: Template Ref support for
arrow()
— The
element
option in
arrow
middleware now natively accepts Vue refs since v0.x/v1.0.0
source
Also changed:
exports .d.mts types
v1.0.3 ·
isPositioned
false when
open
false fix v1.1.5 ·
MaybeReadonlyRefOrGetter
legacy Vue support v1.1.1
Best Practices
Use
whileElementsMounted: autoUpdate
to ensure the floating element stays anchored during scroll, resize, or layout changes. This handles the full lifecycle of positioning listeners automatically
source
Always return the cleanup function when passing a custom function to
whileElementsMounted
(e.g., when providing custom options to
autoUpdate
)
source
useFloating
(
reference
,
floating
,
{
whileElementsMounted
(
reference
,
floating
,
update
)
{
return
autoUpdate
(
reference
,
floating
,
update
,
{
animationFrame
:
true
}
)
;
}
,
}
)
;
Prefer
v-if
for floating elements when using
whileElementsMounted
. If using
v-show
, avoid the
whileElementsMounted
prop and manage the
autoUpdate
lifecycle manually via watchers to prevent performance leaks when the element is hidden
source
Use the
isPositioned
ref to coordinate side effects that require the final position, such as focusing an input or scrolling an element into view
source
const
{
isPositioned
}
=
useFloating
(
reference
,
floating
,
{
open
}
)
;
watch
(
isPositioned
,
(
positioned
)
=>
{
if
(
positioned
)
{
inputRef
.
value
?.
focus
(
)
;
}
}
)
;
Pass getter functions or
Ref
s to
useFloating
options (like
placement
or
middleware
) to enable reactivity. Since v1.1.0, these options support
MaybeReadonlyRefOrGetter
source
Utilize a wrapper element to support CSS transform animations while maintaining the performant
transform: true
positioning (default). The outer element handles positioning, while the inner element handles the animation
source
Synchronize positioning state by passing an
open
ref to
useFloating
. This ensures
isPositioned
is reset and correctly updated across multiple open/close cycles, especially if the reference element moves
source
Pass template refs directly from
ref(null)
to
useFloating
and middleware like
arrow()
. The library automatically unwraps these and waits for the elements to mount before computing coordinates
source
Enable
animationFrame: true
in
autoUpdate
options if the reference element is moved via CSS transforms or other non-layout-triggering animations to maintain perfect anchoring
source