Skip to content

FloatingDelayGroup

Provides context for a group of floating elements that should share a delay which temporarily becomes 1 ms after the first floating element of the group opens.

import {FloatingDelayGroup} from '@floating-ui/react';

This is useful to enable higher discovery of floating elements when they have a hover delay (like tooltips) when their reference elements are placed near each other.

function App() {
  return (
    <FloatingDelayGroup delay={{open: 1000, close: 200}}>
      <Tooltip label="One">
        <button>Ref</button>
      </Tooltip>
      <Tooltip label="Two">
        <button>Ref</button>
      </Tooltip>
      <Tooltip label="Three">
        <button>Ref</button>
      </Tooltip>
    </FloatingDelayGroup>
  );
}

Example

Usage

To enable delay grouping:

  • Wrap the grouped floating components in a <FloatingDelayGroup> provider.
  • useDelayGroup(), a Hook called inside the component, enables grouping for the component and returns the group delay context from the <FloatingDelayGroup> provider.
import {
  FloatingDelayGroup,
  useDelayGroup,
  useHover,
  useFloating,
} from '@floating-ui/react';
 
function Tooltip() {
  const {context} = useFloating();
  const {delay} = useDelayGroup(context);
  const hover = useHover(context, {delay});
}

Props

interface FloatingDelayGroupProps {
  delay: Delay;
  timeoutMs?: number;
}

delay

Required

default: 0

The delay to use for the group.

<FloatingDelayGroup
  // Both open and close delays
  delay={200}
  // Or, configured individually
  delay={{open: 1000, close: 200}}
>
  {/* ... */}
</FloatingDelayGroup>

timeoutMs

default: 0

An optional explicit timeout to use for the group, which represents when grouping logic will no longer be active after the close delay completes. This is useful if you want grouping to “last” longer than the close delay, for example if there is no close delay at all.

<FloatingDelayGroup timeoutMs={500}>
  {/* ... */}
</FloatingDelayGroup>

Transitions

  • isInstantPhase is a boolean that determines whether the delay is currently in the instant phase. This allows you to make transitions instant/faster. See useTransitionStyles.
  • currentId refers to the id of the floating element of the group currently open.
const {currentId, isInstantPhase} = useDelayGroup(context);
 
const instantDuration = 0;
const duration = 200;
 
const {isMounted, styles} = useTransitionStyles(context, {
  duration: isInstantPhase
    ? {
        open: instantDuration,
        close:
          currentId === context.floatingId
            ? duration
            : instantDuration,
      }
    : duration,
  // ...
});

Troubleshooting

The delay returned from useDelayGroup() is 0 by default if your floating components don’t have a provider. This allows you to conditionally use, for example, a delay prop that’s passed directly into the component rather than the group delay from context.