From 1496a10031bdc15a35cb0d572fa9b7293e95dc61 Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Fri, 19 Dec 2025 16:36:49 +0100
Subject: [PATCH 1/6] use a `span` if the target element is not labelable
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This ensures that the DOM is valid, otherwise using a native `<label
for="…">` with an ID that points to a non-labelable element could result
in an issue.

A labelable element is defined here:

> button, input (if the type attribute is not in the Hidden state)
meter, output, progress, select, textarea, form-associated custom
elements
>
> — https://html.spec.whatwg.org/multipage/forms.html#category-label

But it doesn't say anything about custom implementations where you
implement the behavior yourself. E.g.: components with `role="checkbox"`

With this implementation, we fallback to a simple inline `span` which is
not focusable, but is clickable, mimicking the native `<label>`.

We still use the `aria-labelledby` attribute so tools like VoiceOver
work as expected.

Last but not least, the `for` (`htmlFor`) attribute is removed when
dealing with a `span` instead of a native `label`.
---
 .../src/components/label/label.tsx            | 36 +++++++++++++++++--
 1 file changed, 34 insertions(+), 2 deletions(-)

diff --git a/packages/@headlessui-react/src/components/label/label.tsx b/packages/@headlessui-react/src/components/label/label.tsx
index f13a6a7a73..b3df73f74a 100644
--- a/packages/@headlessui-react/src/components/label/label.tsx
+++ b/packages/@headlessui-react/src/components/label/label.tsx
@@ -13,6 +13,7 @@ import React, {
 import { useEvent } from '../../hooks/use-event'
 import { useId } from '../../hooks/use-id'
 import { useIsoMorphicEffect } from '../../hooks/use-iso-morphic-effect'
+import { useServerHandoffComplete } from '../../hooks/use-server-handoff-complete'
 import { useSlot } from '../../hooks/use-slot'
 import { useSyncRefs } from '../../hooks/use-sync-refs'
 import { useDisabled } from '../../internal/disabled'
@@ -126,6 +127,7 @@ function LabelFn<TTag extends ElementType = typeof DEFAULT_LABEL_TAG>(
     passive = false,
     ...theirProps
   } = props
+  let isLabelableElement = useIsLabelableElementById(htmlFor)
   let labelRef = useSyncRefs(ref)
 
   useIsoMorphicEffect(() => context.register(id), [id, context.register])
@@ -209,7 +211,7 @@ function LabelFn<TTag extends ElementType = typeof DEFAULT_LABEL_TAG>(
     ref: labelRef,
     ...context.props,
     id,
-    htmlFor,
+    htmlFor: isLabelableElement ? htmlFor : undefined,
     onClick: handleClick,
   }
 
@@ -230,7 +232,7 @@ function LabelFn<TTag extends ElementType = typeof DEFAULT_LABEL_TAG>(
     ourProps,
     theirProps,
     slot,
-    defaultTag: htmlFor ? DEFAULT_LABEL_TAG : 'div',
+    defaultTag: htmlFor ? (isLabelableElement ? DEFAULT_LABEL_TAG : 'span') : 'div',
     name: context.name || 'Label',
   })
 }
@@ -248,3 +250,33 @@ let LabelRoot = forwardRefWithAs(LabelFn) as _internal_ComponentLabel
 export let Label = Object.assign(LabelRoot, {
   //
 })
+
+function useIsLabelableElementById(id: string | undefined): boolean {
+  let ready = useServerHandoffComplete()
+  return ready && isLabelableElementById(id)
+}
+
+// See: https://html.spec.whatwg.org/multipage/forms.html#category-label
+function isLabelableElementById(id: string | undefined): boolean {
+  if (id === undefined) return false
+  if (typeof window === 'undefined') return false
+
+  let element = document.getElementById(id)
+  if (!element) return false
+
+  if (element.tagName === 'BUTTON') return true
+  if (DOM.isHTMLInputElement(element) && element.type !== 'hidden') return true
+  if (element.tagName === 'METER') return true
+  if (element.tagName === 'OUTPUT') return true
+  if (element.tagName === 'PROGRESS') return true
+  if (element.tagName === 'SELECT') return true
+  if (element.tagName === 'TEXTAREA') return true
+
+  // @ts-expect-error If a custom element exist and is form associated, it will
+  // have a static property `formAssociated` on its class definition.
+  if (window.customElements.get(element.tagName.toLowerCase())?.formAssociated) {
+    return true
+  }
+
+  return false
+}

From 0d0423a7e607379af3ed00d373c3fedbf28bfe62 Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Fri, 19 Dec 2025 16:41:50 +0100
Subject: [PATCH 2/6] simplify click behavior when clicking on our `<Label />`

We already figured out that we only ever use a real `<label>` when we
target a real labelable element. This also means that we can entirely
rely on the native browser behavior for labels.

However, when we are _not_ dealing with a labelable element, we use a
span and therefore we have to perform that `click` logic ourselves
(which we conveniently already had).
---
 .../@headlessui-react/src/components/label/label.tsx  | 11 ++---------
 1 file changed, 2 insertions(+), 9 deletions(-)

diff --git a/packages/@headlessui-react/src/components/label/label.tsx b/packages/@headlessui-react/src/components/label/label.tsx
index b3df73f74a..1519944a27 100644
--- a/packages/@headlessui-react/src/components/label/label.tsx
+++ b/packages/@headlessui-react/src/components/label/label.tsx
@@ -155,13 +155,6 @@ function LabelFn<TTag extends ElementType = typeof DEFAULT_LABEL_TAG>(
       return
     }
 
-    // Labels connected to 'real' controls will already click the element. But we don't know that
-    // ahead of time. This will prevent the default click, such that only a single click happens
-    // instead of two. Otherwise this results in a visual no-op.
-    if (DOM.isHTMLLabelElement(current)) {
-      e.preventDefault()
-    }
-
     // Ensure `onClick` from context is called
     if (
       context.props &&
@@ -171,8 +164,8 @@ function LabelFn<TTag extends ElementType = typeof DEFAULT_LABEL_TAG>(
       context.props.onClick(e)
     }
 
-    if (DOM.isHTMLLabelElement(current)) {
-      let target = document.getElementById(current.htmlFor)
+    if (!DOM.isHTMLLabelElement(current)) {
+      let target = document.getElementById(htmlFor)
       if (target) {
         // Bail if the target element is disabled
         let actuallyDisabled = target.getAttribute('disabled')

From 55dfd06a6c32199b1b85a8ea81a004da69cf035c Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Fri, 19 Dec 2025 17:15:41 +0100
Subject: [PATCH 3/6] add example to playground

---
 playgrounds/react/pages/combinations/form.tsx | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/playgrounds/react/pages/combinations/form.tsx b/playgrounds/react/pages/combinations/form.tsx
index 0244a67c51..61a5b8e822 100644
--- a/playgrounds/react/pages/combinations/form.tsx
+++ b/playgrounds/react/pages/combinations/form.tsx
@@ -1,4 +1,13 @@
-import { Combobox, Field, Input, Label, Listbox, RadioGroup, Switch } from '@headlessui/react'
+import {
+  Checkbox,
+  Combobox,
+  Field,
+  Input,
+  Label,
+  Listbox,
+  RadioGroup,
+  Switch,
+} from '@headlessui/react'
 import { useState } from 'react'
 import { Button } from '../../components/button'
 import { classNames } from '../../utils/class-names'
@@ -112,6 +121,12 @@ export default function App() {
               </Switch.Group>
             </Section>
           </Section>
+          <Section title="Checkbox">
+            <Field className="flex items-center gap-2 p-1">
+              <Checkbox className="data-checked:bg-blue-600 size-4 border bg-gray-200 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2" />
+              <Label>Label for {'<Checkbox />'}</Label>
+            </Field>
+          </Section>
           <Section title="Radio Group">
             <RadioGroup defaultValue="sm" name="size">
               <div className="flex -space-x-px rounded-md bg-white">

From ace9f8672c094a9460165f62408ccad5efa572a8 Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Fri, 19 Dec 2025 17:36:48 +0100
Subject: [PATCH 4/6] add test

---
 .../src/components/label/label.test.tsx       | 39 +++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/packages/@headlessui-react/src/components/label/label.test.tsx b/packages/@headlessui-react/src/components/label/label.test.tsx
index 8f6718c31b..d5acd28488 100644
--- a/packages/@headlessui-react/src/components/label/label.test.tsx
+++ b/packages/@headlessui-react/src/components/label/label.test.tsx
@@ -1,5 +1,16 @@
 import { render } from '@testing-library/react'
 import React, { type ReactNode } from 'react'
+import {
+  CheckboxState,
+  assertActiveElement,
+  assertCheckbox,
+  assertLinkedWithLabel,
+  getCheckbox,
+  getLabel,
+} from '../../test-utils/accessibility-assertions'
+import { click } from '../../test-utils/interactions'
+import { Checkbox } from '../checkbox/checkbox'
+import { Field } from '../field/field'
 import { Label, useLabels } from './label'
 
 jest.mock('../../hooks/use-id')
@@ -71,3 +82,31 @@ it('should be possible to use a LabelProvider and multiple Label components, and
   let { container } = render(<Example />)
   expect(container.firstChild).toMatchSnapshot()
 })
+
+it('should be possible to use a Label with a non labelablea element', async () => {
+  function Example() {
+    return (
+      <Field>
+        <Label>Accept terms and conditions</Label>
+        <Checkbox />
+      </Field>
+    )
+  }
+
+  render(<Example />)
+
+  // Ensure the label is linked to the checkbox
+  assertLinkedWithLabel(getCheckbox(), getLabel()!)
+
+  // Ensure the checkbox is not checked
+  assertCheckbox({ state: CheckboxState.Unchecked })
+
+  // Ensure we can click on the label
+  await click(getLabel())
+
+  // Ensure the checkbox was toggled
+  assertCheckbox({ state: CheckboxState.Checked })
+
+  // Ensure focus is moved to the checkbox
+  assertActiveElement(getCheckbox())
+})

From 0511ef789685751d3b6929151093d0f015b1c92c Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Fri, 19 Dec 2025 17:36:54 +0100
Subject: [PATCH 5/6] ensure `role` is available

`el.role` is undefined in jsdom, but `el.getAttribute('role')` is not.
So we can fallback to that, but short-circuit if `el.target` is
available.
---
 packages/@headlessui-react/src/components/label/label.tsx | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/packages/@headlessui-react/src/components/label/label.tsx b/packages/@headlessui-react/src/components/label/label.tsx
index 1519944a27..74d5bbb093 100644
--- a/packages/@headlessui-react/src/components/label/label.tsx
+++ b/packages/@headlessui-react/src/components/label/label.tsx
@@ -181,12 +181,13 @@ function LabelFn<TTag extends ElementType = typeof DEFAULT_LABEL_TAG>(
         // Ensure we click the element this label is bound to. This is necessary for elements that
         // immediately require state changes, e.g.: Radio & Checkbox inputs need to be checked (or
         // unchecked).
+        let role = target.role || target.getAttribute('role')
         if (
           (DOM.isHTMLInputElement(target) &&
             (target.type === 'file' || target.type === 'radio' || target.type === 'checkbox')) ||
-          target.role === 'radio' ||
-          target.role === 'checkbox' ||
-          target.role === 'switch'
+          role === 'radio' ||
+          role === 'checkbox' ||
+          role === 'switch'
         ) {
           target.click()
         }

From d45e422766e71df2a083998294791621b8f96f82 Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Fri, 19 Dec 2025 17:46:28 +0100
Subject: [PATCH 6/6] update changelog

---
 packages/@headlessui-react/CHANGELOG.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/@headlessui-react/CHANGELOG.md b/packages/@headlessui-react/CHANGELOG.md
index 75f326771a..5531bc54a6 100644
--- a/packages/@headlessui-react/CHANGELOG.md
+++ b/packages/@headlessui-react/CHANGELOG.md
@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - Don’t render `<Portal>` while hydrating ([#3825](https://github.com/tailwindlabs/headlessui/pull/3825))
+- Ensure a `span` is used for non-labelable elements when using `Label` component ([#3831](https://github.com/tailwindlabs/headlessui/pull/3831))
 
 ## [2.2.9] - 2025-09-25