[React] Possible API enhancements

[atomiks]

All of the enhancements that were part of this original post are now implemented. I'm going to convert this to a discussion if you want to talk about other API changes for v1.

[mihkeleidast]

2. Prefix the callback refs with set

Relating to this - one thing I've been slightly annoyed with in the current implementation is that when useFloating return value is forwarded through context, it isn't immediately clear what state.floating is, or why is it a function, or what does it do exactly. To know this one needs to go through the implementation, see where that is forwarded from, and likely would need to go read through Floating UI docs to get the full picture.

So going from ref={state.floating} to ref={state.setFloating} seems better indeed, but it doesn't really improve too much on clarity.

But - since there is also the state.refs variable (which can currently only be used for reading the current ref values), I would actually prefer doing ref={state.refs.setFloating}, as that would make it more clear that this is setting/updating a ref.

[atomiks]

But - since there is also the state.refs variable (which can currently only be used for reading the current ref values), I would actually prefer doing ref={state.refs.setFloating}, as that would make it more clear that this is setting/updating a ref.

So you'd want:

const {refs} = useFloating();

return <>
  <div ref={refs.setReference} />
  <div ref={refs.setFloating} />
</>;

The main use case where that doesn't make sense is when passing in virtual elements in an effect/event handler I guess? Since it doesn't attach itself to the ref prop.

useEffect(() => {
  refs.setReference({ ... });
}, [refs]);

Although since it attaches itself to refs.reference.current, maybe it still does.

[atomiks]

No. 2 and No. 4 are implemented in the latest versions, I just need to switch the docs to use the new API, but the original callback ref aliases will likely be kept around forever (or at worst, with a deprecation warning in the next major), since they add almost no cost, and I don't want to break anyone's code and make upgrading easy.

For No. 3, if implemented, it wouldn't be an API like: useFloating(r, f, options), which is not only complex internally to handle the overload, but makes it impractical to mix and match external sync with using internal refs. So it'd be something like this:

const {refs} = useFloating({
  // You can sync one or the other, allowing you to mix the internal ref
  // setters with external elements
  reference,
  floating,
});

I'd also like to make the main /react package v1 stable sometime soon, maybe by April? It'd have been a year since initial release, and there's been lots of feedback by now especially by @mihkeleidast who has been incredibly helpful solving issues and suggesting use cases. So if you have any suggestions for the API regarding naming or anything else, it'd be great to hear the suggestions before the main release of that package.

[mihkeleidast]

Welp, thanks for the callout, I have been lucky enough to start working on some of our "floating components" exactly at a time floating-ui was release, otherwise I would be one of those legacy Popper users 😅

No. 2 and No. 4 are implemented in the latest versions, I just need to switch the docs to use the new API, but the original callback ref aliases will likely be kept around forever (or at worst, with a deprecation warning in the next major), since they add almost no cost, and I don't want to break anyone's code and make upgrading easy.

Just a thought, but keeping them does keep the API more complex, and likely we'll still need the docs to tell what these are - otherwise someone looking at the return value of useFloating might be a bit confused?

Also, if one would like to make the returned value from the hook accessible through context (like the official component examples also suggest)...

export const useDrawer = () => {
  const data = useFloating();

  return React.useMemo(
    () => ({
      ...data,
    }),
    [data]
  );
};

But would like to keep the shared context value lean, the extra props are sort of a nuisance? I guess one could do const { reference, floating, ...data } = useFloating(); to clean that up, which is also fine, just wanted to bring out a second perspective.

---

I'll try to write up some general thoughts now.

For the most part, the library works great! One thing I have noticed is the general configuration complexity. I suppose this is sort of a necessity for a library that tries to be fully tree-shakeable, where every feature is strictly opt-in. Though, my experience so far is that even if a single component does not use all of the exports from floating-ui, likely a user of this lib will build several components based on it, so in the end most of the library will end up in the bundle anyway. I think the only hooks I don't have a usecase for yet is useCustomLogic and useTypeahead (though I haven't looked into the latter too much yet). I also don't use useListNavigation yet, but I do have a component that has the same stuff implemented on my side as custom code, so I'll likely refactor that at some point.

Just as an example, my Tooltip component imports and uses all of these from floating-ui:

import {
  Placement,
  offset,
  flip,
  shift,
  autoUpdate,
  useFloating,
  useInteractions,
  useHover,
  useFocus,
  useRole,
  useDismiss,
  FloatingPortal,
  arrow,
  Side,
  autoPlacement,
  safePolygon,
  FloatingNode,
  useFloatingNodeId,
  useDelayGroupContext,
  useDelayGroup,
  useTransitionStatus,
} from '@floating-ui/react';

A whopping 23 line import statement (minus 2 if you remove type imports). But in the component itself, all of these need to be configured one-by-one as well, so there's a lot of configuration. Some features need to be configured in multiple places or through multiple hooks, which is sort of weird, even though I understand the reasoning.

2. Delay group configuration

This one has three exports: FloatingDelayGroup, useDelayGroupContext and useDelayGroup.

Additionally, it needs to be integrated to both onOpenChange in useFloating and useHover. The example in the docs does not account for the fact that most likely such component also allows configuring the delay on Tooltip directly (i.e. when not using a group), which further complicates the configuration.

Since the delay group functionality only affects useHover, maybe it could be integrated into that more tightly, with less configuration? For example, could the useDelayGroup be used internally in useHover, lessening the need for configuration? There is the question that useDelayGroup needs an id, but then again, in many places, I provide a nodeId to useFloating, which could perhaps be reused through the context (in my case, I am using the same nodeId value for both)?

Also, for the integration in onOpenChange, I don't know the technical reasoning behing this, but isn't this known through the context already, when the component/floating hook is open, i.e. couldn't this be internalized as well?

3. The complexity of nested floating elements

This one has 4 required imports: FloatingTree, FloatingNode, useFloatingNodeId, useFloatingParentNodeId. Another - useFloatingTree - is opt-in, i.e. that I haven't needed yet. I think most of my floating elements use FloatingNode, and most also use FloatingTree, with Tooltip being the outlier in the sense that it cannot have nested floating elements in it, so it does not have to implement it. But, all in all, I think a lot of the components that use this library need to all of the four components/hooks at the moment, so maybe it could be somewhat simplified.

There are several "nuisances" regarding this.

One is the fact that basically every component that uses FloatingTree, needs to have that wrapper component implemented, which is sort of boilerplatey. I get why that is necessary - i.e. that the context provider needs to be a parent component of the one that actually uses the useFloating and other hooks, but still, sort of a configuration hell. This could potentially be simplified by internalizing useFloatingParentNodeId into FloatingTree - FloatingTree internally could decide based on the hook value if it wants to wrap it with a new context provider, or just return children. Then the wrapper component would only look like this:

export function Popover(props) {
  return (
    <FloatingTree>
      <PopoverComponent {...props} />
    </FloatingTree>
  );
}

Another, more of a docs issue for FloatingNode specifically - I haven't yet had the time to delve into this, but I'm not sure if the reference element needs to be in FloatingNode or not, or is it only necessary to wrap the floating element in FloatingNode? My thinking is that the reference element can also be external to the floating component (just externally controlled from far away or passed in through a prop), in which case there is likely some special handling? Not a huge issue, it's easy to just wrap everything, but I don't always understand where it actually needs to be.

Third - useId, useFloatingNodeId, FloatingNode cross-configuration. Some of my components use both useId (just for accessibility purposes, to link elements together) and useFloatingNodeId (for the tree context) right now.

const PopoverInner = () => {
  const id = useId();
  const nodeId = useFloatingNodeId();
  const data= useFloating({
    nodeId,
  });
  return (
    <FloatingNode id={nodeId}>
       {children}
    </FloatingNode>
  );
};

Would it be possible to, instead, use something like this?

const PopoverInner = () => {
  const id = useId();
  const data= useFloating({
    id,
  });
  return <FloatingNode id={id}>{children}</FloatingNode>;
};

I.e. let FloatingNode itself take care of the registering of the node id to the tree context? I assume this can be complicated, as the useFloating hook also needs to know about the nodeId for some reason, so there is likely a need to call those hooks in a very specific order?

---

Stopping now, I hope I did not ramble too much here 😅 All in all, I think everything is great and - most importantly - it works. Just would like some of the features' configuration to be a bit simpler.

[atomiks]

@mihkeleidast thank you for writing that up, it's very helpful!

If you have any more thoughts, some kind of paginated document (Notion?) with each page being a separate API feedback would be great actually

Just a thought, but keeping them does keep the API more complex, and likely we'll still need the docs to tell what these are - otherwise someone looking at the return value of useFloating might be a bit confused?

I think they can have tsdoc notes for IntelliSense noting they are aliases for the refs.set* functions. But in practice, new users don't really need to know or care about them otherwise from this point forward. When returning them from context I don't see much of an issue, but I guess there should be some kind of note in the docs at least...

For the most part, the library works great! One thing I have noticed is the general configuration complexity

There are definitely a lot of imports, as you mentioned due to tree-shaking reasons. For example, safePolygon could easily be a prop of useHover but is externalized to make it tree-shakeable.

The alternative is a prop-based API with minimal imports to use, but large bundle size. Maybe we can try grouping some parts together better somehow to reduce the number of imports needed. I'd ideally like to keep it as fairly tree-shakeable as possible like the main positioning packages, but there's a limit where it becomes too much (and I think the /react package is definitely over it as you've mentioned.)

I think the main positioning library has a much better balance of prop-based config and separate modules.

Delay group configuration

Looking at this, it looks like an oversight and can indeed be made simpler, I'll look into it.

The complexity of nested floating elements

It's clear that there should just be more coordination of the main hook with less decoupling overall (and therefore configuration needed). As you mentioned, in practice many of the parts are used anyway, so separate tree-shakeable parts aren't that much help bundle size-wise.

[mihkeleidast]

If you have any more thoughts, some kind of paginated document (Notion?) with each page being a separate API feedback would be great actually

Hmm, maybe it would be best if we collect the "ideas" here and then you can split stuff up to separate issues if something needs working on / discussed further? I think that would potentially encourage feedback from other users more, another tool like Notion will likely go unnoticed for most.

Adding one more thing here now:

Enabling/disabling the entire hook

Currently, in several components, I have either a enabled or disabled prop that needs to also be forwarded to the floating hooks.

For the interaction hooks, this needs to be specified to each subhook one by one:

const { getReferenceProps, getFloatingProps } = useInteractions([
  useHover(context, {
    enabled: !disabled,
  }),
  useFocus(context, {
    enabled: !disabled,
  }),
  useRole(context, { enabled: !disabled }),
  useDismiss(context, { enabled: !disabled }),
]);

While I think that the prop on the subhooks themselves is necessary to be kept (there can be more complex usecases where only a single hook can be disabled on some condition), for such "global disabling", it would be good if we could specify this only once to useFloating directly, which could then act as the default condition through the context:

const { context, } = useFloating({
  enabled: !disabled,
});

const { getReferenceProps, getFloatingProps } = useInteractions([
  useHover(context),
  useFocus(context),
  useRole(context),
  useDismiss(context),
]);

Might be even beneficial for perf, if disabled, we can bail out of some of the work being done in the core hook?

[Nantris]

Based on the docs:

• I'm not clear on how to configure the arrow with React
• I'm not clear on how to configure autoupdate with React
• I'm not clear on how to transition tooltips into view - for example in a situation where a single tooltip is shared across elements and it's already open on ElementA, but when ElementB is clicked we want it to fade in, not appear (achievable with keyframes but what a pain, is there a better way?)

[mihkeleidast]

@atomiks for consideration: perhaps FloatingDelayGroup should be renamed to just FloatingGroup?

We ran into an issue with small reference elements that have long tooltips that also have safePolygon closing enabled: https://codesandbox.io/s/sharp-chandrasekhar-18gn6s?file=/src/Tooltip.tsx

This often results in a situation where both of the tooltips remain open, because of the safePolygon closing, which is sort of unfortunate result visually:

This is especially concerning when moving from "b" to "a", as with the current portal root logic (related: #2094), the "b" tooltip will remain on top of "a" tooltip, even though it is rendered later interaction-wise.

Ideally, in those situations, we'd like to say that there should only be a single Tooltip open at a time in that group. So I found that we can actually leverage FloatingDelayGroup for this: https://codesandbox.io/s/competent-golick-nfshxc?file=/src/App.tsx

But <FloatingDelayGroup delay={0}> as an API feels weird to use, as the 0 delay should already be the default and have no effect, but it still does. So maybe it would make more sense to make rename that component and related hooks to something more universal, and the delay sharing could then be an optional feature of that grouping logic?

[atomiks]

@mihkeleidast while that works, if you try to move the cursor into the tooltip by quickly traversing the other element, it ends up closing expectedly and showing the other tooltip even if that wasn't your intent. Maybe not the biggest deal in that situation, but for submenus it's more important.

The lib's best solution for it right now is combining blockPointerEvents and restMs, but the actual best way would be determining how fast the cursor is moving when it's over the other group elements to determine the actual intent of the cursor, which currently isn't provided as an option. This way, you don't fire hover events over the other element, but it also doesn't block the hover events too "eagerly" either if you want to look at the other element's tooltip. restMs works ok but could be better.

[mihkeleidast]

Yup, I'm aware of the intent tradeoff, I think it's fine in that scenario, as the other solutions also have their own tradeoffs and this is likely the easiest to implement/maintain. But I don't really want to discuss the particulars of that too much in this issue - the idea is still that the grouping logic can be used for more things than just delay grouping, which is not evident from the current naming logic or documentation. What do you think about that? Should it only be used for delays, so the other uses are discouraged (i.e. they may break when updating), or is that a valid usecase, in which case it would be good to at least document it / rename the components?

[atomiks]

I think renaming it without Delay is fine, as you can also use restMs with no actual delay IIRC

[atomiks]

I plan on creating a react/v1 branch to make a bunch of these changes this week/end. The list of changes I have in mind currently are:

• Make x/y default to 0 instead of null
• Rename FloatingOverlay to FloatingBackdrop to be more descriptive and in line with ::backdrop native selector
• Rename FloatingDelayGroup to FloatingGroup
• Re-think pointer-based options, like ignoreMouse, mouseOnly etc given that Linux Chrome returns "pen" sometimes despite using a mouse, so the current options are currently "wrong" in some cases.
• Unify more APIs to simplify usage, e.g. useList API that composes useListNavigation and useTypeahead into one — basically reduce how much "glue" is needed to piece things together while still maintaining maximum flexibility/composability, as @mihkeleidast has pointed out already for other APIs.
• Make useMergeRefs and useInteractions variadic instead of passing an array? Small thing but the array can seem a bit awkward and it's not actually needed.
• • Possibly some others as I look over the API and see what needs improving.

[mihkeleidast]

Bumping some of the other issues that might be considered breaking and as such, perhaps would be good to try to solve before v1? Namely:

• [React] Focus management and prop getters for external reference #2128
  1. From this I think the general approach of having to have a separate external store to be able to share data between far-away reference/floating elements is fine. I'm in the process of implementing that in my project this week, will at least report back with some examples.
  2. Non-modal focus management with such approach / singletons is an issue. My idea in fix: focus management with tabbable elements in between reference and floating element #2154 does not work well with screen readers, so this might need some completely different approach (for example wrapping the reference with a FloatingReference component so the guards would b rendered in the correct place)? I sorta get that that this might not be necessary for many, but it might also be that many just don't care about focus management enough to deal with getting this resolved.
• [React] Define the root node for FloatingPortal instead of the portal subroot node #2094
  1. I'll try to compile a list of examples that work unexpectedly with the current implementation. Best case scenario is that there aren't any big issues, then this can be forgotten. But if I find some problems & we deem those need to be fixed somehow, might also be better to do it before v1, as this would be breaking the API?

I of course understand that it might not be feasible to push everything into v1, but maybe it would be good to understand if those issues can be solved with simple "feature updates" or if they will require breaking APIs, which would potentially need to be punted to faraway future release (assuming you don't want to do breaking changes too often).

[jquense]

IDK if this is ther right place, but i'd like to throw my hand up for wanted an easier time passing reference elements to the useFloating hook. As is most of our API's allow consumers to pass in an element as the reference so we have this mildly awkward useLayoutEffect to sync the prop reference to floating ui. Would be great if the hook options simply accepted a reference element as an option, vs returning a ref.

[atomiks]

@jquense I think that's No. 3 in the list in the original post ("external element synchronization") which you should mix/match with the refs setters:

Possible APIs to synchronize with an external value:

useFloating({
  reference,
  floating,
});

useFloating({
  referenceElement,
  floatingElement,
});

useFloating({
  elements: {
    reference,
    floating,
  }
});

[smellai]

Hi, can anyone provide an example on how the external reference should look like? Given the note in the docs says:

Note
Make sure the external elements are stored in state, not in a ref. React does not permit reading or writing refs during render, and they are not reactive to updates, so the position won’t update if the element changes.

  const {refs} = useFloating();
 
  useLayoutEffect(() => {
    refs.setReference(referenceEl);
    refs.setFloating(floatingEl);
  }, [refs, referenceEl, floatingEl]);
}

[atomiks]

@smellai store the element in state (here it is with a type):

const [referenceEl, setReferenceEl] = React.useState<HTMLElement | null>(null);
const {refs} = useFloating();

useLayoutEffect(() => {
  refs.setReference(referenceEl);
}, [refs, referenceEl]);

return <div ref={setReferenceEl} />

---

Note: you will be able to do this in the next version, which will release within a couple of days:

const [referenceEl, setReferenceEl] = React.useState<HTMLElement | null>(null);

// In the next version:
useFloating({
  elements: {
    reference: referenceEl,
  }
});

return <div ref={setReferenceEl} />

In either case you should use state, not a ref, to make it reactive to updates.

[smellai]

@atomiks any update? 🙏

[atomiks]

@smellai update on what? If you mean the external element synchronization, that's been released in the latest version

[smellai]

oh thanks! I will try that! I was expecting this issue to be referenced or something similar I guess :)

[basickarl]

@atomiks How would you deal with forwarded refs (i.e. ref: React.ForwardedRef<unknown>) ? The useFloating expects a ReferenceType.

Here is some code:

const Test = React.forwardRef(function Test(
  { allowedPlacements = PLACEMENTS, portal = true, ...props }: TestProps,
  ref: React.ForwardedRef<MutableRefObject<any>>
) {
  const [open, setOpen] = useState(false);

  const { refs, floatingStyles, context } = useFloating({
    open: open,
    onOpenChange: setOpen,
  });

  const click = useClick(context);
  const dismiss = useDismiss(context);

  const { getReferenceProps, getFloatingProps } = useInteractions([ // How to use getReferenceProps in this instance?
    click,
    dismiss,
  ]);

  useEffect(() => {
    const { current = null } = (ref as MutableRefObject<any>) || {};
    if (current) {
      refs.setReference(current);
    }
  }, [ref, refs]);

  return (
    <>
      {open && (
        <div
          ref={refs.setFloating}
          style={floatingStyles}
          {...getFloatingProps()}
        >
          Floating element
        </div>
      )}
    </>
  );
});

Or is it not possible to use a ref? Also how does one set prop getter on a ref? https://floating-ui.com/docs/react#prop-getters I can't find how to do it in the docs.

Her eis a sandbox, useClick doesn't seem to work: https://codesandbox.io/s/floating-ui-useclick-not-working-s7ct31

[atomiks]

@basickarl you're describing a React data flow problem at its core (or even just a scoping problem really), and there's an open issue here: #2128

Let's imagine you manually wanted to put onClick={() => ...} on the reference element JSX in your example. How would you change the open state? You'd need to hoist the open state declaration into the parent component or wherever the reference is for that to work.

Generally there are five patterns that work in this scenario:

• The compound component pattern: all the re-usable examples on the docs do this. Both the reference element and floating element components/JSX are in scope, so data flow naturally works.
• The cloneElement pattern: your reference JSX is passed as a prop (usually children) and the ref and getReferenceProps can be attached like: cloneElement(children, getReferenceProps({ref: refs.setReference}))
• The render props pattern: your reference JSX receives the props via render prop: <Tooltip renderReference={getProps => <button {...getProps()} />} />
• The hoisting pattern: hoist the useFloating call higher in the component tree to where the reference component/JSX is so that it's in scope, and pass data down to the floating component as props.
• The sync pattern: sync getReferenceProps to a parent with a layout effect, like:

const [getReferenceProps, setGetReferenceProps] = useState();

return <>
  <button {...getReferenceProps?.()} />
  <Tooltip setGetReferenceProps={setGetReferenceProps} />
</>;

useLayoutEffect(() => {
  onGetReferencePropsChange(() => getReferenceProps);
}, [getReferenceProps]);

In this case make sure you're using state too, not a plain ref, to externally synchronize the element (second code block here).

---

There may be more, or a dedicated way to improve this scenario. Let me know if you have any ideas.

[atomiks]

Converting this to a discussion since the original parts of this issue are already implemented now.

[Handaz]

Hello, @atomiks!
We are currently using popper.js in our UI kit library and planning to migrate to Floating UI. Could you please clarify if current version of React package is stable or any breaking changes/enhancements to API are coming? If stable, why isn't it in v1 or higher?

[Handaz]

@atomiks can you give an answer?

[atomiks]

Sorry for not seeing this. @floating-ui/react-dom (positioning-only) is not in v0, it's currently in v2 after implementing the API enhancements discussed here. @floating-ui/react on the other hand is still v0 but still follows proper SemVer, and I'm trying to avoid making major breaking changes up until it hits v1 now.

The reason the main package is not v1 yet is because the interactions API is far more complex and detailed than the positioning API, which is small and straightforward. v0 gives me freedom to make minor breaking changes without publishing a whole new major version until the API is set right.

[Handaz]

Thank you for clarifying!

[mihkeleidast]

Hey again! Adding one more thing. I'm implementing a listbox right now and trying to use useListNavigation, useTypeahead, FloatingList and useListItem to create a composable API:

<Listbox value="option-1">
    <ListboxOption value="option-1" label="Simple option" />
</Listbox>

These hooks currently operate on indices, but listboxes (or selects, etc) as form components usually want to operate based on values. I guess the indices work nicely for menus where there is no "value".

This is pretty obvious from the composable select example as well, as a "real" select component would also have a way of specifying defaultValue/value/onChange, which should be related to value props on options.

So, to make it work with values, it is currently necessary to manually create a mapping between the indices and values, and then derive one or the other from the controlled value passed into the component.

One small but useful improvement would be to allow collecting arbitrary data with FloatingList/useListItem in addition to the current elements & labels. So then the options data (value, label, icon, etc) would be collected to the list level automatically, deriving the index from there is quite easy.

But supporting "value"-base selection as an alternative could be even better.