harlan-zw/floating-ui-vue-skilld

floating-ui/floating-ui @floating-ui/[email protected]

Tags: latest: 1.1.11

References: Docs

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<Element> 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 Refs 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