Fix Maximum update depth exceeded due to Transition (#3782)

This PR fixes an issue where you could run into a `Maximum update depth
exceeded` error in the `Listbox`, `Menu` or `Combobox` component in
combination with the `transition` prop.

It seems like some people ran into this, but I was never able to
reproduce it. But now I figured out what the issue is, how to reproduce
it and this PR should fix it as well (it at least fixes the `Maximum
update depth exceeded` I could reproduce).

To reproduce it, you don't need a lot of code, but you do need a
particular setup:
```tsx
import { Listbox, ListboxButton, ListboxOption, ListboxOptions } from '@headlessui/react'
import { useState } from 'react'

let options = ['apple', 'banana', 'orange', 'grape', 'pear']

export default function App() {
  let [value, setValue] = useState('apple')

  return (
    <>
      {/* Required to reproduce the issue */}
      <div className="min-h-dvh" />

      <Listbox value={value} onChange={setValue}>
        <ListboxButton>{value}</ListboxButton>
        <ListboxOptions transition>
          {options.map((option) => (
            <ListboxOption key={option} value={option}>
              {option}
            </ListboxOption>
          ))}
        </ListboxOptions>
      </Listbox>
    </>
  )
}
```

This setup means that you have to scroll down to see the Listbox. When
you open the Listbox, the `ListboxOptions` will be rendered increasing
the height of the page. If you then close it again, the page will
decrease in height again, causing the issue to happen.

The next question is, why does the crash happen?

The crash happens because we are updating some internal state based on
whether the `ListboxButton` moved or not. The reason we track whether
the button moved or not is to improve the UX (a bit ironic I know,
because it could crash…)

In the Listbox component (and some others like Menu and Combobox), we
track whether a button moved on the screen when you close the dropdown.
If it does move, we will immediately hide the Listbox without any
transitions.

This is done to improve the UX because we don't want to see a fading-out
dropdown somewhere else on the screen.

Maybe it's easier if I show you an example. This example is using our UI
Kit, Catalyst: https://catalyst.tailwindui.com/docs/listbox

**Example 1:**

1. Open the dropdown
2. Click outside or press Escape to close it
3. Notice the subtle fade-out transition


https://github.com/user-attachments/assets/0eecffd7-f4fe-4543-8a48-433dd27f1bf7

**Example 2:**

1. Open the dropdown
2. Press tab to focus the next element on the page
3. Notice the subtle fade-out transition


https://github.com/user-attachments/assets/3bec2178-1f15-40cd-ab1e-ae8ca333bd92

**Example 3:**

Now we're going to do something very similar, but this time the next
focusable element will be just outside of what is visual to the user.
This will cause the browser to scroll and scroll the new element into
view. We'll make the page smaller by opening devtools.

1. Open the dropdown
2. Press tab to focus the next element on the page
3. Notice how the the dropdown is completely gone, no transitions
whatsoever


https://github.com/user-attachments/assets/4abd7fd4-250b-4f91-a172-5954e9fccae7

**Example 4:**

Up until now, all these make sense as a user. But here is an example of
what would happen if we didn't close the dropdown immediately when the
button moved.

Same steps and similar setup as Example 3, but without the special code
that detects button moves.

It's going to be quick, but look near the end of this video. Once I
press tab, you will see the dropdown fade out and linger around near the
top of the screen.


https://github.com/user-attachments/assets/993fdec5-6a8c-468f-bbf8-6003f7be7048

(This was a little tricky to reproduce here because when you tab, the
active element will be scrolled into view automatically by the browser,
so the button sits in the middle of the page. But we want to make sure
the dropdown button is still in the viewport~ish. This is why it's
zoomed out a bit.)

---

Now that we established that, why did it crash in some scenarios?

The first important part is the `transition` prop. A transition allows
us to keep the dropdown visible even though its internal state is
"closed". This is important so that we will wait until all CSS
transitions are done before actually unmounting the component.

The next important part is about the extra div (`<div class="min-h-dvh"
/>`) in the reproduction code, because it will force a scrollbar.
Opening and closing the listbox will change the height of the page. This
in turn will move the button up to make room for the dropdown part,
therefore the `button` will be marked as moved.

However, we keep checking whether the button moved compared to the
initial position, which could result in a loop:

0. Close the listbox.
1. Compute button position at **position A**
2. Re-render happens, and button is now at **position B** because the
dropdown part is gone
3. Re-render happens, and button is now at **position A** again, because
it's considered at the same initial position so instead of instantly
hiding we actually show it again because the `visible` state (thanks to
the `transition`) is still set to true.
4. Re-render happens, and button is now at **position B** again because
now the dropdown is rendered again
5. …**position A**
6. …**position B**
7. …

To actually solve the issue, we have to make sure that once the button
is marked as moved, it will stay marked as "moved" until the `enabled`
boolean (argument to the hook) changes again.

I also did some internal refactors by moving this logic into the
existing state machines instead of relying on React and when things
render. I therefore also got rid of the `useDidElementMove` hook
entirely.

## Test plan

2. Error does not reproduce with this code.
2. The expected behavior in Catalyst still works as expected.

Simplified reproduction of the crash in action:

### Before


https://github.com/user-attachments/assets/46254740-dac6-4d95-ba1a-aef4b4b7082c

### After 


https://github.com/user-attachments/assets/9ee4350b-3bd0-4f07-b4a5-edb4f3cb3d78

Fixes: #3655
Fixes: #3562

---------

Co-authored-by: Jordan Pittman <[email protected]>

Author: RobinMalfait

packages/@headlessui-react/CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Ensure we are not freezing data when the `static` prop is used ([#3779](https://github.com/tailwindlabs/headlessui/pull/3779))
 - Ensure `onChange` types are contravariant instead of bivariant ([#3781](https://github.com/tailwindlabs/headlessui/pull/3781))
 - Support `<summary>` as a focusable element inside `<details>` ([#3389](https://github.com/tailwindlabs/headlessui/pull/3389))
+- Fix `Maximum update depth exceeded` crash when using `transition` prop ([#3782](https://github.com/tailwindlabs/headlessui/pull/3782))
 
 ## [2.2.7] - 2025-07-30
 

packages/@headlessui-react/src/components/combobox/combobox-machine.ts

@@ -2,6 +2,11 @@ import { Machine } from '../../machine'
 import { ActionTypes as StackActionTypes, stackMachines } from '../../machines/stack-machine'
 import type { EnsureArray } from '../../types'
 import { Focus, calculateActiveIndex } from '../../utils/calculate-active-index'
+import {
+  ElementPositionState,
+  computeVisualPosition,
+  detectMovement,
+} from '../../utils/element-movement'
 import { sortByDomNode } from '../../utils/focus-management'
 import { match } from '../../utils/match'
 
@@ -74,6 +79,9 @@ export interface State<T> {
   buttonElement: HTMLButtonElement | null
   optionsElement: HTMLElement | null
 
+  // Track input to determine if it moved
+  inputPositionState: ElementPositionState
+
   __demoMode: boolean
 }
 
@@ -96,6 +104,8 @@ export enum ActionTypes {
   SetInputElement,
   SetButtonElement,
   SetOptionsElement,
+
+  MarkInputAsMoved,
 }
 
 function adjustOrderedState<T>(
@@ -160,13 +170,17 @@ type Actions<T> =
   | { type: ActionTypes.SetInputElement; element: HTMLInputElement | null }
   | { type: ActionTypes.SetButtonElement; element: HTMLButtonElement | null }
   | { type: ActionTypes.SetOptionsElement; element: HTMLElement | null }
+  | { type: ActionTypes.MarkInputAsMoved }
 
 let reducers: {
   [P in ActionTypes]: <T>(state: State<T>, action: Extract<Actions<T>, { type: P }>) => State<T>
 } = {
   [ActionTypes.CloseCombobox](state) {
     if (state.dataRef.current?.disabled) return state
     if (state.comboboxState === ComboboxState.Closed) return state
+    let inputPositionState = state.inputElement
+      ? ElementPositionState.Tracked(computeVisualPosition(state.inputElement))
+      : state.inputPositionState
 
     return {
       ...state,
@@ -181,6 +195,8 @@ let reducers: {
       // for example, not scrolling to the active option in a virtual list
       activationTrigger: ActivationTrigger.Other,
 
+      inputPositionState,
+
       __demoMode: false,
     }
   },
@@ -197,11 +213,17 @@ let reducers: {
           activeOptionIndex: idx,
           comboboxState: ComboboxState.Open,
           __demoMode: false,
+          inputPositionState: ElementPositionState.Idle,
         }
       }
     }
 
-    return { ...state, comboboxState: ComboboxState.Open, __demoMode: false }
+    return {
+      ...state,
+      comboboxState: ComboboxState.Open,
+      inputPositionState: ElementPositionState.Idle,
+      __demoMode: false,
+    }
   },
   [ActionTypes.SetTyping](state, action) {
     if (state.isTyping === action.isTyping) return state
@@ -404,6 +426,14 @@ let reducers: {
     if (state.optionsElement === action.element) return state
     return { ...state, optionsElement: action.element }
   },
+  [ActionTypes.MarkInputAsMoved](state) {
+    if (state.inputPositionState.kind !== 'Tracked') return state
+
+    return {
+      ...state,
+      inputPositionState: ElementPositionState.Moved,
+    }
+  },
 }
 
 export class ComboboxMachine<T> extends Machine<State<T>, Actions<T>> {
@@ -438,6 +468,7 @@ export class ComboboxMachine<T> extends Machine<State<T>, Actions<T>> {
       buttonElement: null,
       optionsElement: null,
       __demoMode,
+      inputPositionState: ElementPositionState.Idle,
     })
   }
 
@@ -464,6 +495,20 @@ export class ComboboxMachine<T> extends Machine<State<T>, Actions<T>> {
       this.on(ActionTypes.OpenCombobox, () => stackMachine.actions.push(id))
       this.on(ActionTypes.CloseCombobox, () => stackMachine.actions.pop(id))
     }
+
+    // Track whether the input moved or not
+    this.disposables.group((d) => {
+      this.on(ActionTypes.CloseCombobox, (state) => {
+        if (!state.inputElement) return
+
+        d.dispose()
+        d.add(
+          detectMovement(state.inputElement, state.inputPositionState, () => {
+            this.send({ type: ActionTypes.MarkInputAsMoved })
+          })
+        )
+      })
+    })
   }
 
   actions = {
@@ -640,6 +685,10 @@ export class ComboboxMachine<T> extends Machine<State<T>, Actions<T>> {
 
       return true
     },
+
+    didInputMove(state: State<T>) {
+      return state.inputPositionState.kind === 'Moved'
+    },
   }
 
   reduce(state: Readonly<State<T>>, action: Actions<T>): State<T> {

packages/@headlessui-react/src/components/combobox/combobox.tsx

@@ -1261,6 +1261,21 @@ function OptionsFn<TTag extends ElementType = typeof DEFAULT_OPTIONS_TAG>(
     ),
   })
 
+  // We keep track whether the input moved or not, we only check this when the
+  // combobox state becomes closed. If the input moved, then we want to cancel
+  // pending transitions to prevent that the attached `ComboboxOptions` is still
+  // transitioning while the input visually moved away.
+  //
+  // If we don't cancel these transitions then there will be a period where the
+  // `ComboboxOptions` is visible and moving around because it is trying to
+  // re-position itself based on the new position.
+  let didInputMove = useSlice(machine, machine.selectors.didInputMove)
+
+  // Now that we know that the input did move or not, we can either disable the
+  // panel and all of its transitions, or rely on the `visible` state to hide
+  // the panel whenever necessary.
+  let panelEnabled = didInputMove ? false : visible
+
   useIsoMorphicEffect(() => {
     data.optionsPropsRef.current.static = props.static ?? false
   }, [data.optionsPropsRef, props.static])
@@ -1392,7 +1407,7 @@ function OptionsFn<TTag extends ElementType = typeof DEFAULT_OPTIONS_TAG>(
           slot,
           defaultTag: DEFAULT_OPTIONS_TAG,
           features: OptionsRenderFeatures,
-          visible,
+          visible: panelEnabled,
           name: 'Combobox.Options',
         })}
       </ComboboxDataContext.Provider>

packages/@headlessui-react/src/components/listbox/listbox-machine.ts

@@ -1,6 +1,11 @@
 import { Machine, batch } from '../../machine'
 import { ActionTypes as StackActionTypes, stackMachines } from '../../machines/stack-machine'
 import { Focus, calculateActiveIndex } from '../../utils/calculate-active-index'
+import {
+  ElementPositionState,
+  computeVisualPosition,
+  detectMovement,
+} from '../../utils/element-movement'
 import { sortByDomNode } from '../../utils/focus-management'
 import { match } from '../../utils/match'
 
@@ -65,6 +70,9 @@ interface State<T> {
 
   pendingShouldSort: boolean
   pendingFocus: { focus: Exclude<Focus, Focus.Specific> } | { focus: Focus.Specific; id: string }
+
+  // Track button to determine if it moved
+  buttonPositionState: ElementPositionState
 }
 
 export enum ActionTypes {
@@ -82,6 +90,8 @@ export enum ActionTypes {
   SetOptionsElement,
 
   SortOptions,
+
+  MarkButtonAsMoved,
 }
 
 function adjustOrderedState<T>(
@@ -135,19 +145,25 @@ type Actions<T> =
   | { type: ActionTypes.SetButtonElement; element: HTMLButtonElement | null }
   | { type: ActionTypes.SetOptionsElement; element: HTMLElement | null }
   | { type: ActionTypes.SortOptions }
+  | { type: ActionTypes.MarkButtonAsMoved }
 
 let reducers: {
   [P in ActionTypes]: <T>(state: State<T>, action: Extract<Actions<T>, { type: P }>) => State<T>
 } = {
   [ActionTypes.CloseListbox](state) {
     if (state.dataRef.current.disabled) return state
     if (state.listboxState === ListboxStates.Closed) return state
+    let buttonPositionState = state.buttonElement
+      ? ElementPositionState.Tracked(computeVisualPosition(state.buttonElement))
+      : state.buttonPositionState
+
     return {
       ...state,
       activeOptionIndex: null,
       pendingFocus: { focus: Focus.Nothing },
       listboxState: ListboxStates.Closed,
       __demoMode: false,
+      buttonPositionState,
     }
   },
   [ActionTypes.OpenListbox](state, action) {
@@ -169,6 +185,7 @@ let reducers: {
       listboxState: ListboxStates.Open,
       activeOptionIndex,
       __demoMode: false,
+      buttonPositionState: ElementPositionState.Idle,
     }
   },
   [ActionTypes.GoToOption](state, action) {
@@ -394,6 +411,14 @@ let reducers: {
       pendingShouldSort: false,
     }
   },
+  [ActionTypes.MarkButtonAsMoved](state) {
+    if (state.buttonPositionState.kind !== 'Tracked') return state
+
+    return {
+      ...state,
+      buttonPositionState: ElementPositionState.Moved,
+    }
+  },
 }
 
 export class ListboxMachine<T> extends Machine<State<T>, Actions<T>> {
@@ -412,6 +437,7 @@ export class ListboxMachine<T> extends Machine<State<T>, Actions<T>> {
       pendingShouldSort: false,
       pendingFocus: { focus: Focus.Nothing },
       __demoMode,
+      buttonPositionState: ElementPositionState.Idle,
     })
   }
 
@@ -447,6 +473,20 @@ export class ListboxMachine<T> extends Machine<State<T>, Actions<T>> {
       this.on(ActionTypes.OpenListbox, () => stackMachine.actions.push(id))
       this.on(ActionTypes.CloseListbox, () => stackMachine.actions.pop(id))
     }
+
+    // Track whether the button moved or not
+    this.disposables.group((d) => {
+      this.on(ActionTypes.CloseListbox, (state) => {
+        if (!state.buttonElement) return
+
+        d.dispose()
+        d.add(
+          detectMovement(state.buttonElement, state.buttonPositionState, () => {
+            this.send({ type: ActionTypes.MarkButtonAsMoved })
+          })
+        )
+      })
+    })
   }
 
   actions = {
@@ -566,6 +606,10 @@ export class ListboxMachine<T> extends Machine<State<T>, Actions<T>> {
       if (state.activationTrigger === ActivationTrigger.Pointer) return false
       return this.isActive(state, id)
     },
+
+    didButtonMove(state: State<T>) {
+      return state.buttonPositionState.kind === 'Moved'
+    },
   }
 
   reduce(state: Readonly<State<T>>, action: Actions<T>): State<T> {

packages/@headlessui-react/src/components/listbox/listbox.tsx

@@ -24,7 +24,6 @@ import { useActivePress } from '../../hooks/use-active-press'
 import { useByComparator, type ByComparator } from '../../hooks/use-by-comparator'
 import { useControllable } from '../../hooks/use-controllable'
 import { useDefaultValue } from '../../hooks/use-default-value'
-import { useDidElementMove } from '../../hooks/use-did-element-move'
 import { useDisposables } from '../../hooks/use-disposables'
 import { useElementSize } from '../../hooks/use-element-size'
 import { useEvent } from '../../hooks/use-event'
@@ -610,20 +609,19 @@ function OptionsFn<TTag extends ElementType = typeof DEFAULT_OPTIONS_TAG>(
     allowed: useCallback(() => [buttonElement, optionsElement], [buttonElement, optionsElement]),
   })
 
-  // We keep track whether the button moved or not, we only check this when the menu state becomes
-  // closed. If the button moved, then we want to cancel pending transitions to prevent that the
-  // attached `MenuItems` is still transitioning while the button moved away.
+  // We keep track whether the button moved or not, we only check this when the
+  // listbox state becomes closed. If the button moved, then we want to cancel
+  // pending transitions to prevent that the attached `ListboxOptions` is
+  // still transitioning while the button visually moved away.
   //
-  // If we don't cancel these transitions then there will be a period where the `MenuItems` is
-  // visible and moving around because it is trying to re-position itself based on the new position.
-  //
-  // This can be solved by only transitioning the `opacity` instead of everything, but if you _do_
-  // want to transition the y-axis for example you will run into the same issue again.
-  let didElementMoveEnabled = listboxState !== ListboxStates.Open
-  let didButtonMove = useDidElementMove(didElementMoveEnabled, buttonElement)
-
-  // Now that we know that the button did move or not, we can either disable the panel and all of
-  // its transitions, or rely on the `visible` state to hide the panel whenever necessary.
+  // If we don't cancel these transitions then there will be a period where the
+  // `ListboxOptions` is visible and moving around because it is trying to
+  // re-position itself based on the new position.
+  let didButtonMove = useSlice(machine, machine.selectors.didButtonMove)
+
+  // Now that we know that the button did move or not, we can either disable the
+  // panel and all of its transitions, or rely on the `visible` state to hide
+  // the panel whenever necessary.
   let panelEnabled = didButtonMove ? false : visible
 
   // We should freeze when the listbox is visible but "closed". This means that