@floating-ui/react

Refactors

• Bump @floating-ui/react-dom to v2 (#2300)

View CHANGELOG for breaking changes

Bug Fixes

• fix(useTypeahead): opening when typing a space on non-button reference with useClick, and timing of onTypingChange callback setting to false (#2305)

• fix(FloatingArrow): add ability to override internal styles (#2308)

• fix(FloatingFocusManager): better handle subtree changes (#2305)

Bug Fixes

• fix(FloatingList): properly update when list contains only one item (#2294)

• fix(FloatingFocusManager): separate initialFocus and returnFocus effects (#2295)

  Wait for unmount transition before returning focus

• fix(FloatingFocusManager): ignore outside guards while transitioning out (#2295)

New Features

• feat(safePolygon): replace restMs option with requireIntent boolean option (#2284)

  When multiple reference elements next to each other have hoverable floating elements, requireIntent (true by default) ensures the triangle polygon does not block hover events too aggressively compared to restMs by calculating the cursor speed to determine intent.

• feat: FloatingList and useListItem exports (#2269)

  This enables easy creation of composable children APIs without needing to map children and passing an index as a prop — including the ability to nest items in another tag or component.

Bug Fixes

• fix(useClick): ignore Space keyup if Space keydown on same element did not precede it (#2277)

• fix(useDelayGroupContext): isInstantPhase bool sometimes being incorrectly false (#2286)

• fix(FloatingPortal): adjust cleanup strategy to better work with React.StrictMode and conditional rendering (#2286)

Bug Fixes

• fix(FloatingFocusManager): respect autoFocus prop on children (#2264)

• fix(FloatingFocusManager): wait for tree nodes context to be updated (#2265)

• fix(FloatingFocusManager): wait for microtask before selecting tabbable elements for initial focus (#2270)

Bug Fixes

• fix(useHover): check pointerType for contains check (#2255)

Bug Fixes

• fix(useInteractions): merging function props that return values (#2244)

• fix(useClientPoint): keep anchored to reference on autoUpdate in applicable scenarios (#2249)

• fix(useHover): touch interactivity of floating element without safePolygon (#2253)

• fix(useTransitionStyles): reduce initial re-renders (#2254)

Refactors

• refactor(FloatingPortal): preserve subroot structure (#2240)

  When specifying a custom root or id, the floating element is always injected into a new subroot inside of it. The subroot has a unique id to ensure aria-owns is referenced correctly when multiple floating elements are rendered at the same time. This makes portal container behavior consistent whether props are specified or not.

  If you don't want the subroot node always in the DOM, the library now supports conditionally rendering FloatingPortal based on the open/mounted state.

• refactor(useFloatingPortalNode): remove enabled prop (#2240)

Bug Fixes

• fix(useListNavigation): allow scheduled/async list population on arrow keydown open (#2236)

• fix(useDismiss): close when outside press dismissing on an inline element in Firefox (#2238)

• fix: allow FloatingPortal to be conditionally rendered based on open state (#2239)

Bug Fixes

• fix: remove timeouts for focus guards on Safari (#2227)

New Features

• feat: useClientPoint interaction hook (#2179)

  This hook provides the ability to position the floating element relative to a client "point" reference. By default, "client" means mouse event coordinates since they possess clientX/Y values, so it follows the cursor when open. You can also use explicit x and y client coordinates.

  If you've used Tippy.js, it provides similar functionality to followCursor while being a bit more general.

  const clientPoint = useClientPoint(context, {
    enabled?: boolean,
    // Restrict the client point to an axis, use the DOM
    // reference as the other axis
    axis?: 'both' | 'x' | 'y',
    // Position explicitly at these client coordinates
    x?: number | null,
    y?: number | null,
  });
  

Refactors

• refactor(useDismiss): default bubbles.escapeKey option to false, and allow bubbling prevention to work without using FloatingTree (#2207)

• refactor(useTypeahead): reduce default resetMs to 750 from 1000 (#2213)

• refactor(FloatingArrow): internally double strokeWidth so it matches borderWidth values (#2223)

  ⚠️ strokeWidths larger than the floating element's borderWidth are not supported.

• refactor(useTypeahead): add onTypingChange callback to allow setting a local ref and deprecate context.dataRef.current.typing value (#2213)

Bug Fixes

• fix(useFloating): return extended elements from hook (#2209)

• fix(useListNavigation): use mounted rather than open state to focus parent floating in tree (#2210)

• fix(FloatingFocusManager): make initialFocus and returnFocus non-reactive (#2211)

• fix: share floatingId via context object (#2203)

• fix(FloatingFocusManager): reset preventing returnFocus with closeOnFocusOut={false} when tabbing out then back in (#2214)

• fix(FloatingFocusManager): mutate internal preventReturnFocusRef instead of returnFocusRef (#2215)

• fix(useTypeahead): improve logic (#2213)

  • Reset timeout from a non-match
  • Don't require a role be set and stop propagation/prevent default if typeahead is in use

• fix(FloatingFocusManager): ensure returnFocus of a nested floating element can return to a root reference if it wasn't focused upon open (such as with a pointer) (#2221)

• fix(FloatingArrow): prevent transparency overlap if the floating element border and stroke are both partially transparent (#2223)

• fix(FloatingFocusManager): ensure initialFocus works if re-opening floating element while it was transitioning out (#2221)

• fix(FloatingArrow): ensure correct vertical size with larger stroke widths (#2223)

• fix(FloatingArrow): allow height > width (#2223)

Bug Fixes

• fix(FloatingArrow): ignore SSR hydration warnings (#2198)

New Features

• feat: FloatingArrow component (#2195)

  Provides the ability to render a customizable <svg> arrow element within a floating element that is automatically positioned, without needing to setup complex styles.

Bug Fixes

• fix(useTypeahead): allow typeahead when currentTarget contains target (#2173)

• fix(types): re-export middleware options types (#2175)

• fix(useTransitionStyles): apply initial styles in unmounted status (#2177)

  This allows a transition-delay prop style to work correctly on the first/initial render.

• fix(useHover): ensure scrolling away from reference after hovering it closes floating element when safePolygon is being used with a close delay and the cursor did not move (#2178)

• fix(useHover): prevent floating element from closing when it overlaps the reference element when using safePolygon (#2180)

• fix: allow platform object to be passed to the useFloating hook (#2176)

• fix(types): add @deprecation notice to non-ref nested element setters (#2175)

Bug Fixes

• fix: dependency issue with Yarn PnP (#2157)

Refactors

• refactor(safePolygon): change blockPointerEvents option to false by default and revert to pointer-events strategy instead of real polygon — this works more reliably but has notable side-effects. (#2149)

  If you need to enable blockPointerEvents, and want to avoid the two side-effects with scrolling containers:

  1. Can't scroll while hovering over the reference element
  2. macOS' auto-hiding scrollbar(s) appear

  A [data-floating-ui-safe-polygon] selector is available as a parent like so:

  [data-floating-ui-safe-polygon] [data-scrolling-container] {
    pointer-events: auto;
  }
  
  [data-floating-ui-safe-polygon] [data-scrolling-container] > div {
    pointer-events: none;
  }
  

  <div data-scrolling-container>
    <div>
      blocked content
      {/* reference inside here */}
    </div>
  </div>
  

  It's also recommended that it's set to false in tests.

Bug Fixes

• fix(FloatingPortal): allow empty id string to add no id attribute (#2148)

Performance Improvements

• perf: make getItemProps getter change less frequently (#2147)

Bug Fixes

• fix: prevent setState loop when placing getFloatingProps as a dependency of a hook and the ref setter is inside (#2130)

• fix(useFocus): only prevent onBlur if an outside focus guard was hit (#2131)

• fix(useListNavigation): avoid synchronizing the activeIndex if the floating element is unmounting (transitioning out) (#2134)

• fix(safePolygon): improve cursor landing logic (#2135)

New Features

• feat(useDelayGroupContext): return isInstantPhase boolean for conditionally applying fast transition durations with useTransition hooks (#2119)

Bug Fixes

• fix: avoid arrow re-export collision (#2113)

• fix(safePolygon): destroy polygon once cursor is over floating element rect when it overlaps it (#2116)

• fix(FloatingDelayGroup): simplify usage by syncing current id internally (#2117)

  You no longer need to wrap your onOpenChange callback or use setCurrentId from the delay context.

  Usage can just be:

  onOpenChange: setOpen,
  

• fix(useHover): prevent clearing a delay timeout unexpectedly if requesting an open while an unmount is in transition (#2118)

• fix: improve useDismiss bubbles logic for nested floating elements (#2114)

• fix: avoid useFloating re-export collision (#2113)

New Features

• Support new @floating-ui/react-dom APIs (#2101)

Bug Fixes

• fix(FloatingFocusManager): prevent FloatingPortal focus guard from not respecting closeOnFocusOut option (#2105)

• fix(FloatingFocusManager): prevent sync return focus edge cases (#2108)

• fix(FloatingFocusManager): aria-hidden not being applied to outside nodes when no reference is present (#2101)

• fix(useListNavigation): scrollIntoView should be invoked if the modality is pointer when the selectedIndex matches activeIndex (#2108)

New Features

• feat: useTransitionStatus and useTransitionStyles hooks (#2089)

  These hooks make it easy to add CSS transitions to your floating elements, namely if you aren't using a spring library already like framer-motion/react-spring etc, but especially makes "placement-aware" transitions straightforward.

  A basic symmetric scale transition looks like:

  const {isMounted, styles} = useTransitionStyles(context, {
    initial: {
      opacity: 0,
      transform: 'scale(0.8)',
    },
  });
  
  return isMounted && <div style={styles} />;
  

  A placement/side-aware transition looks like:

  const {isMounted, styles} = useTransitionStyles(context, {
    initial: ({side}) => ({
      opacity: 0,
      transform: {
        top: 'translateY(5px)',
        bottom: 'translateY(-5px)',
        right: 'translateX(-5px)',
        left: 'translateX(5px)',
      }[side],
    }),
  });
  
  return isMounted && <div style={styles} />;
  

Bug Fixes

• fix: preserve backwards-compatibility for multiple reference() calls for old virtual element position technique (#2092)

  Going forward, the new positionReference callback ref is recommended instead, this is only to ensure upgrading does not break your old code.

• fix(FloatingFocusManager): make return focus calls sync under certain conditions (#2092)

  Only in Strict Mode, Safari would not navigate via arrow down keys due to sync navigation (<Menu> example)

Bug Fixes

• fix(useClick): prevent keyboard-like or undefined pointer types being considered as mouse for ignoreMouse option (#2077)

  Fix regression introduced in v0.15.0

• fix(types): export interaction hook prop types (#2081)

  fix(docs): add missing IntelliSense helpers/links

Performance Improvements

• perf: replace ?? with || where possible to reduce bundle size transpilation cost (#2079)

New Features

• feat(useDismiss): allow specifying different value for outside press bubbling and escape key bubbling (#2040)

• feat: useMergeRefs hook (#2060)

• feat(FloatingDelayGroup): add timeoutMs prop (#2066)

  If there's no close delay, you might still want the delays to end up grouped even if none of the tooltips are currently open within a certain period of time. Instead of relying on the close delay, you can instead rely on the timeoutMs prop. This also helps with unmounting animations if you want to allow it to be interruptible and continue grouping even if there is a close delay, e.g. timeoutMs = closeDelayMs + animationDurationMs

• feat(useListNavigation): scrollItemIntoView option (#2061)

  Any external effects that were handling .scrollIntoView() manually can now be removed and instead use this option, which supports boolean | ScrollIntoViewOptions. It's true by default, using nearest options.

• feat: positionReference callback ref (#2065)

  This adds a dedicated API to separate the events reference from the positioning reference and is more reliable than the previous technique suggested in the docs.

  You can call it with a real element or a virtual element:

  function App() {
    const {reference, positionReference} = useFloating();
  
    return (
      <>
        <div ref={reference} />
        <div ref={positionReference} />
      </>
    );
  }
  

  As a result, the generic reference type is now narrowed on refs.domReference.current not refs.reference.current (which is always wide).

Refactors

• refactor(FloatingDelayGroup): change default delay to 0 (from 1000) (#2055)

Bug Fixes

• fix(FloatingFocusManager): avoid returning focus to reference after unhovering (#2049)

• fix(FloatingFocusManager): prevent closing on focusout when moving from non-portalled floating element to nested portalled floating element (#2068)

• fix(safePolygon): use real polygon for blockPointerEvents option (#2069)

  This prevents unwanted side effects compared to the previous "global holes" strategy.

New Features

• feat(FloatingFocusManager): closeOnFocusOut prop (#2022) (#2027)

Refactors

• @floating-ui/react-dom-interactions is now @floating-ui/react. (#2027)

  There are no breaking changes between v0.13.0 to this version, just the name of the package.

  You should be able to easily do a find-and-replace with the string to change all your imports:

  npm uninstall @floating-ui/react-dom-interactions
  npm install @floating-ui/react
  

Bug Fixes

• fix(useDismiss): make outsidePress reactive to primitive values, but also referentially stable if specifying a function value (#2024) (#2027)