Freeze values as soon as possible (#3802)

This PR fixes an issue with the `Listbox` component where we didn't
freeze the value soon enough.

This happens when state lives in the parent, and is updated via an
`onChange`.

What is currently happening:

1. User clicks on a listbox option, this should do 3 things:
  1. Call the `onChange` with the new value
  2. Close the listbox
3. "Freeze" the value, so the old value is still showing while the
listbox options are closing.

The problem is that calling the `onChange` updates the value in the
parent, and the component re-renders with the new value. At the time we
freeze the value, we already received the new value so we are freezing
the incorrect value. This causes a visual glitch. See reproduction:
tailwindlabs/tailwind-plus-issues#1761

This PR fixes that by changing the order a little bit so we freeze the
value as early as possible.

So now, when the user clicks on an option, we trigger a `SelectOption`
action. This will track whether we should freeze the value or not in
state immediately. After that, we call the `onChange`, and then close
the listbox.

Since we know we want to freeze the value _before_ calling `onChange`,
we can be sure we are freezing the correct (old) value.

## Test plan

Made a little video but with a duration of 1000 instead of 100 so you
can clearly see the old value and no visual jumps while the listbox is
closing.


https://github.com/user-attachments/assets/971b8ff4-2b03-4f6e-99af-f21f14d37930



Fixes: tailwindlabs/tailwind-plus-issues#1761

---------

Co-authored-by: Jordan Pittman <jordan@cryptica.me>

Author: RobinMalfait

packages/@headlessui-react/CHANGELOG.md

@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Infer `Combobox` type based on `onChange` handler ([#3798](https://github.com/tailwindlabs/headlessui/pull/3798))
 - Allow home/end key default behavior inside `ComboboxInput` when `Combobox` is closed ([#3798](https://github.com/tailwindlabs/headlessui/pull/3798))
 - Ensure interacting with a `Dialog` on iOS works after interacting with a disallowed area ([#3801](https://github.com/tailwindlabs/headlessui/pull/3801))
+- Freeze Listbox values as soon as possible when closing ([#3802](https://github.com/tailwindlabs/headlessui/pull/3802))
 
 ## [2.2.8] - 2025-09-12
 

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

@@ -65,6 +65,8 @@ interface State<T> {
   activeOptionIndex: number | null
   activationTrigger: ActivationTrigger
 
+  frozenValue: boolean
+
   buttonElement: HTMLButtonElement | null
   optionsElement: HTMLElement | null
 
@@ -82,6 +84,7 @@ export enum ActionTypes {
   GoToOption,
   Search,
   ClearSearch,
+  SelectOption,
 
   RegisterOptions,
   UnregisterOptions,
@@ -137,6 +140,7 @@ type Actions<T> =
     }
   | { type: ActionTypes.Search; value: string }
   | { type: ActionTypes.ClearSearch }
+  | { type: ActionTypes.SelectOption; value: T }
   | {
       type: ActionTypes.RegisterOptions
       options: { id: string; dataRef: ListboxOptionDataRef<T> }[]
@@ -181,6 +185,7 @@ let reducers: {
 
     return {
       ...state,
+      frozenValue: false,
       pendingFocus: action.focus,
       listboxState: ListboxStates.Open,
       activeOptionIndex,
@@ -338,6 +343,22 @@ let reducers: {
     if (state.searchQuery === '') return state
     return { ...state, searchQuery: '' }
   },
+  [ActionTypes.SelectOption](state) {
+    if (state.dataRef.current.mode === ValueMode.Single) {
+      // The moment you select a value in single value mode, we want to close
+      // the listbox and freeze the value to prevent UI flicker.
+      return { ...state, frozenValue: true }
+    }
+
+    // We have an event listener for `SelectOption`, but that will only be
+    // called when the state changes. In multi-value mode we don't have a state
+    // change but we still want to trigger the event listener. Therefore we
+    // return a new object to trigger that event.
+    //
+    // Not the cleanest, but that's why we have this, instead of just returning
+    // `state`.
+    return { ...state }
+  },
   [ActionTypes.RegisterOptions]: (state, action) => {
     let options = state.options.concat(action.options)
 
@@ -436,6 +457,7 @@ export class ListboxMachine<T> extends Machine<State<T>, Actions<T>> {
       optionsElement: null,
       pendingShouldSort: false,
       pendingFocus: { focus: Focus.Nothing },
+      frozenValue: false,
       __demoMode,
       buttonPositionState: ElementPositionState.Idle,
     })
@@ -487,6 +509,15 @@ export class ListboxMachine<T> extends Machine<State<T>, Actions<T>> {
         )
       })
     })
+
+    this.on(ActionTypes.SelectOption, (_, action) => {
+      this.actions.onChange(action.value)
+
+      if (this.state.dataRef.current.mode === ValueMode.Single) {
+        this.actions.closeListbox()
+        this.state.buttonElement?.focus({ preventScroll: true })
+      }
+    })
   }
 
   actions = {
@@ -556,22 +587,21 @@ export class ListboxMachine<T> extends Machine<State<T>, Actions<T>> {
     ) => {
       this.send({ type: ActionTypes.OpenListbox, focus })
     },
+
     selectActiveOption: () => {
       if (this.state.activeOptionIndex !== null) {
-        let { dataRef, id } = this.state.options[this.state.activeOptionIndex]
-        this.actions.onChange(dataRef.current.value)
-
-        // It could happen that the `activeOptionIndex` stored in state is actually null,
-        // but we are getting the fallback active option back instead.
-        this.send({ type: ActionTypes.GoToOption, focus: Focus.Specific, id })
+        let { dataRef } = this.state.options[this.state.activeOptionIndex]
+        this.actions.selectOption(dataRef.current.value)
+      } else if (this.state.dataRef.current.mode === ValueMode.Single) {
+        this.actions.closeListbox()
+        this.state.buttonElement?.focus({ preventScroll: true })
       }
     },
-    selectOption: (id: string) => {
-      let option = this.state.options.find((item) => item.id === id)
-      if (!option) return
 
-      this.actions.onChange(option.dataRef.current.value)
+    selectOption: (value: T) => {
+      this.send({ type: ActionTypes.SelectOption, value })
     },
+
     search: (value: string) => {
       this.send({ type: ActionTypes.Search, value })
     },
@@ -600,6 +630,10 @@ export class ListboxMachine<T> extends Machine<State<T>, Actions<T>> {
       return activeOptionIndex !== null ? options[activeOptionIndex]?.id === id : false
     },
 
+    hasFrozenValue(state: State<T>) {
+      return state.frozenValue
+    },
+
     shouldScrollIntoView(state: State<T>, id: string) {
       if (state.__demoMode) return false
       if (state.listboxState !== ListboxStates.Open) return false

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

@@ -595,7 +595,7 @@ function OptionsFn<TTag extends ElementType = typeof DEFAULT_OPTIONS_TAG>(
   //
   // When the `static` prop is used, we should never freeze, because rendering
   // is up to the user.
-  let shouldFreeze = visible && listboxState === ListboxStates.Closed && !props.static
+  let shouldFreeze = useSlice(machine, machine.selectors.hasFrozenValue) && !props.static
 
   // Frozen state, the selected value will only update visually when the user re-opens the <Listbox />
   let frozenValue = useFrozenData(shouldFreeze, data.value)
@@ -671,14 +671,7 @@ function OptionsFn<TTag extends ElementType = typeof DEFAULT_OPTIONS_TAG>(
         event.preventDefault()
         event.stopPropagation()
 
-        if (machine.state.activeOptionIndex !== null) {
-          let { dataRef } = machine.state.options[machine.state.activeOptionIndex]
-          machine.actions.onChange(dataRef.current.value)
-        }
-        if (data.mode === ValueMode.Single) {
-          flushSync(() => machine.actions.closeListbox())
-          machine.state.buttonElement?.focus({ preventScroll: true })
-        }
+        machine.actions.selectActiveOption()
         break
 
       case match(data.orientation, {
@@ -872,11 +865,7 @@ function OptionFn<
 
   let handleClick = useEvent((event: { preventDefault: Function }) => {
     if (disabled) return event.preventDefault()
-    machine.actions.onChange(value)
-    if (data.mode === ValueMode.Single) {
-      flushSync(() => machine.actions.closeListbox())
-      machine.state.buttonElement?.focus({ preventScroll: true })
-    }
+    machine.actions.selectOption(value)
   })
 
   let handleFocus = useEvent(() => {

packages/@headlessui-react/src/hooks/use-transition.ts

@@ -165,7 +165,7 @@ export function useTransition(
       },
       done() {
         if (cancelledRef.current) {
-          if (typeof element.getAnimations === 'function' && element.getAnimations().length > 0) {
+          if (hasPendingTransitions(element)) {
             return
           }
         }
@@ -304,3 +304,11 @@ function prepareTransition(
   // Reset the transition to what it was before
   node.style.transition = previous
 }
+
+function hasPendingTransitions(node: HTMLElement) {
+  let animations = node.getAnimations?.() ?? []
+
+  return animations.some((animation) => {
+    return animation instanceof CSSTransition && animation.playState !== 'finished'
+  })
+}