From b05d2dbed84fb886be7b09959844079cc663ffac Mon Sep 17 00:00:00 2001
From: Varun Chawla <varun_6april@hotmail.com>
Date: Sun, 15 Feb 2026 02:12:45 -0800
Subject: [PATCH] [DOM] Treat hidden as an overloaded boolean to support
 hidden="until-found"

The hidden attribute was treated as a plain boolean, which meant any
truthy value was coerced to an empty string. This prevented using the
hidden="until-found" value that is now supported in all major browsers
(Chrome 102+, Firefox 139+, Safari 26.2+).

Move hidden from the boolean attribute list to the overloaded boolean
list (alongside capture and download), so that:
- hidden={true} renders as hidden=""
- hidden={false} removes the attribute
- hidden="until-found" renders as hidden="until-found"

Fixes #24740
---
 .../src/client/ReactDOMComponent.js           |  4 +-
 .../src/client/ReactFiberConfigDOM.js         |  2 +-
 .../src/server/ReactFizzConfigDOM.js          | 24 ++++--
 .../src/shared/ReactDOMUnknownPropertyHook.js |  1 -
 .../src/__tests__/ReactDOMComponent-test.js   | 78 +++++++++++++++++--
 ...eactDOMServerIntegrationAttributes-test.js | 61 ++++++++-------
 6 files changed, 128 insertions(+), 42 deletions(-)

diff --git a/packages/react-dom-bindings/src/client/ReactDOMComponent.js b/packages/react-dom-bindings/src/client/ReactDOMComponent.js
index 1b25e3727023..1f7d44821347 100644
--- a/packages/react-dom-bindings/src/client/ReactDOMComponent.js
+++ b/packages/react-dom-bindings/src/client/ReactDOMComponent.js
@@ -762,7 +762,6 @@ function setProp(
     case 'disablePictureInPicture':
     case 'disableRemotePlayback':
     case 'formNoValidate':
-    case 'hidden':
     case 'loop':
     case 'noModule':
     case 'noValidate':
@@ -782,6 +781,7 @@ function setProp(
       break;
     }
     // Overloaded Boolean
+    case 'hidden':
     case 'capture':
     case 'download': {
       // An attribute that can be used as a flag as well as with a value.
@@ -2855,7 +2855,6 @@ function diffHydratedGenericElement(
       case 'disablePictureInPicture':
       case 'disableRemotePlayback':
       case 'formNoValidate':
-      case 'hidden':
       case 'loop':
       case 'noModule':
       case 'noValidate':
@@ -2878,6 +2877,7 @@ function diffHydratedGenericElement(
         );
         continue;
       }
+      case 'hidden':
       case 'capture':
       case 'download': {
         hydrateOverloadedBooleanAttribute(
diff --git a/packages/react-dom-bindings/src/client/ReactFiberConfigDOM.js b/packages/react-dom-bindings/src/client/ReactFiberConfigDOM.js
index 94d37cfc902d..31ee89013156 100644
--- a/packages/react-dom-bindings/src/client/ReactFiberConfigDOM.js
+++ b/packages/react-dom-bindings/src/client/ReactFiberConfigDOM.js
@@ -156,7 +156,7 @@ export type Props = {
   autoFocus?: boolean,
   children?: mixed,
   disabled?: boolean,
-  hidden?: boolean,
+  hidden?: boolean | string,
   suppressHydrationWarning?: boolean,
   dangerouslySetInnerHTML?: mixed,
   style?: {
diff --git a/packages/react-dom-bindings/src/server/ReactFizzConfigDOM.js b/packages/react-dom-bindings/src/server/ReactFizzConfigDOM.js
index a93c32a947f1..b5f73cfefe62 100644
--- a/packages/react-dom-bindings/src/server/ReactFizzConfigDOM.js
+++ b/packages/react-dom-bindings/src/server/ReactFizzConfigDOM.js
@@ -1701,7 +1701,6 @@ function pushAttribute(
     case 'disablePictureInPicture':
     case 'disableRemotePlayback':
     case 'formNoValidate':
-    case 'hidden':
     case 'loop':
     case 'noModule':
     case 'noValidate':
@@ -1723,6 +1722,7 @@ function pushAttribute(
       }
       return;
     }
+    case 'hidden':
     case 'capture':
     case 'download': {
       // Overloaded Boolean
@@ -5848,12 +5848,19 @@ function writeStyleResourceAttributeInJS(
       attributeValue = '' + (value: any);
       break;
     }
-    // Booleans
+    // Overloaded Booleans
     case 'hidden': {
       if (value === false) {
         return;
       }
-      attributeValue = '';
+      if (value === true) {
+        attributeValue = '';
+      } else {
+        if (__DEV__) {
+          checkAttributeStringCoercion(value, attributeName);
+        }
+        attributeValue = '' + (value: any);
+      }
       break;
     }
     // Santized URLs
@@ -6043,12 +6050,19 @@ function writeStyleResourceAttributeInAttr(
       break;
     }
 
-    // Booleans
+    // Overloaded Booleans
     case 'hidden': {
       if (value === false) {
         return;
       }
-      attributeValue = '';
+      if (value === true) {
+        attributeValue = '';
+      } else {
+        if (__DEV__) {
+          checkAttributeStringCoercion(value, attributeName);
+        }
+        attributeValue = '' + (value: any);
+      }
       break;
     }
 
diff --git a/packages/react-dom-bindings/src/shared/ReactDOMUnknownPropertyHook.js b/packages/react-dom-bindings/src/shared/ReactDOMUnknownPropertyHook.js
index f45e477d876f..6a3f1106be2a 100644
--- a/packages/react-dom-bindings/src/shared/ReactDOMUnknownPropertyHook.js
+++ b/packages/react-dom-bindings/src/shared/ReactDOMUnknownPropertyHook.js
@@ -293,7 +293,6 @@ function validateProperty(tagName, name, value, eventRegistry) {
             case 'disablePictureInPicture':
             case 'disableRemotePlayback':
             case 'formNoValidate':
-            case 'hidden':
             case 'loop':
             case 'noModule':
             case 'noValidate':
diff --git a/packages/react-dom/src/__tests__/ReactDOMComponent-test.js b/packages/react-dom/src/__tests__/ReactDOMComponent-test.js
index 0f0986dde8e3..6581b887ef42 100644
--- a/packages/react-dom/src/__tests__/ReactDOMComponent-test.js
+++ b/packages/react-dom/src/__tests__/ReactDOMComponent-test.js
@@ -3614,16 +3614,18 @@ describe('ReactDOMComponent', () => {
       const root = ReactDOMClient.createRoot(container);
 
       await act(() => {
-        root.render(<div hidden="false" ref={current => (el = current)} />);
+        root.render(
+          <div disabled="false" ref={current => (el = current)} />,
+        );
       });
       assertConsoleErrorDev([
-        'Received the string `false` for the boolean attribute `hidden`. ' +
+        'Received the string `false` for the boolean attribute `disabled`. ' +
           'The browser will interpret it as a truthy value. ' +
-          'Did you mean hidden={false}?\n' +
+          'Did you mean disabled={false}?\n' +
           '    in div (at **)',
       ]);
 
-      expect(el.getAttribute('hidden')).toBe('');
+      expect(el.getAttribute('disabled')).toBe('');
     });
 
     it('warns on the potentially-ambiguous string value "true"', async function () {
@@ -3632,17 +3634,79 @@ describe('ReactDOMComponent', () => {
       const root = ReactDOMClient.createRoot(container);
 
       await act(() => {
-        root.render(<div hidden="true" ref={current => (el = current)} />);
+        root.render(
+          <div disabled="true" ref={current => (el = current)} />,
+        );
       });
       assertConsoleErrorDev([
-        'Received the string `true` for the boolean attribute `hidden`. ' +
+        'Received the string `true` for the boolean attribute `disabled`. ' +
           'Although this works, it will not work as expected if you pass the string "false". ' +
-          'Did you mean hidden={true}?\n' +
+          'Did you mean disabled={true}?\n' +
           '    in div (at **)',
       ]);
 
+      expect(el.getAttribute('disabled')).toBe('');
+    });
+  });
+
+  describe('Overloaded Boolean: hidden attribute', function () {
+    it('accepts boolean true', async function () {
+      let el;
+      const container = document.createElement('div');
+      const root = ReactDOMClient.createRoot(container);
+
+      await act(() => {
+        root.render(<div hidden={true} ref={current => (el = current)} />);
+      });
+
       expect(el.getAttribute('hidden')).toBe('');
     });
+
+    it('accepts boolean false and removes the attribute', async function () {
+      let el;
+      const container = document.createElement('div');
+      const root = ReactDOMClient.createRoot(container);
+
+      await act(() => {
+        root.render(<div hidden={false} ref={current => (el = current)} />);
+      });
+
+      expect(el.getAttribute('hidden')).toBe(null);
+    });
+
+    it('accepts the string value "until-found"', async function () {
+      let el;
+      const container = document.createElement('div');
+      const root = ReactDOMClient.createRoot(container);
+
+      await act(() => {
+        root.render(
+          <div hidden="until-found" ref={current => (el = current)} />,
+        );
+      });
+
+      expect(el.getAttribute('hidden')).toBe('until-found');
+    });
+
+    it('accepts arbitrary string values', async function () {
+      let el;
+      const container = document.createElement('div');
+      const root = ReactDOMClient.createRoot(container);
+
+      await act(() => {
+        root.render(
+          <div hidden="until-found" ref={current => (el = current)} />,
+        );
+      });
+
+      expect(el.getAttribute('hidden')).toBe('until-found');
+
+      await act(() => {
+        root.render(<div hidden="true" ref={current => (el = current)} />);
+      });
+
+      expect(el.getAttribute('hidden')).toBe('true');
+    });
   });
 
   describe('Hyphenated SVG elements', function () {
diff --git a/packages/react-dom/src/__tests__/ReactDOMServerIntegrationAttributes-test.js b/packages/react-dom/src/__tests__/ReactDOMServerIntegrationAttributes-test.js
index be5ff44b8cd1..c4083c8721db 100644
--- a/packages/react-dom/src/__tests__/ReactDOMServerIntegrationAttributes-test.js
+++ b/packages/react-dom/src/__tests__/ReactDOMServerIntegrationAttributes-test.js
@@ -119,69 +119,78 @@ describe('ReactDOMServerIntegration', () => {
 
     describe('boolean properties', function () {
       itRenders('boolean prop with true value', async render => {
+        const e = await render(<div disabled={true} />);
+        expect(e.getAttribute('disabled')).toBe('');
+      });
+
+      itRenders('boolean prop with false value', async render => {
+        const e = await render(<div disabled={false} />);
+        expect(e.getAttribute('disabled')).toBe(null);
+      });
+    });
+
+    describe('overloaded boolean properties (hidden)', function () {
+      itRenders('hidden prop with true value', async render => {
         const e = await render(<div hidden={true} />);
         expect(e.getAttribute('hidden')).toBe('');
       });
 
-      itRenders('boolean prop with false value', async render => {
+      itRenders('hidden prop with false value', async render => {
         const e = await render(<div hidden={false} />);
         expect(e.getAttribute('hidden')).toBe(null);
       });
 
-      itRenders('boolean prop with self value', async render => {
+      itRenders('hidden prop with "until-found" value', async render => {
+        const e = await render(<div hidden="until-found" />);
+        expect(e.getAttribute('hidden')).toBe('until-found');
+      });
+
+      itRenders('hidden prop with self value', async render => {
         const e = await render(<div hidden="hidden" />);
-        expect(e.getAttribute('hidden')).toBe('');
+        expect(e.getAttribute('hidden')).toBe('hidden');
       });
 
-      // this does not seem like correct behavior, since hidden="" in HTML indicates
-      // that the boolean property is present. however, it is how the current code
-      // behaves, so the test is included here.
-      itRenders('boolean prop with "" value', async render => {
+      itRenders('hidden prop with "" value', async render => {
         const e = await render(<div hidden="" />);
-        expect(e.getAttribute('hidden')).toBe(null);
+        expect(e.getAttribute('hidden')).toBe('');
       });
 
-      // this seems like it might mask programmer error, but it's existing behavior.
-      itRenders('boolean prop with string value', async render => {
+      itRenders('hidden prop with string value', async render => {
         const e = await render(<div hidden="foo" />);
-        expect(e.getAttribute('hidden')).toBe('');
+        expect(e.getAttribute('hidden')).toBe('foo');
       });
 
-      // this seems like it might mask programmer error, but it's existing behavior.
-      itRenders('boolean prop with array value', async render => {
+      itRenders('hidden prop with array value', async render => {
         const e = await render(<div hidden={['foo', 'bar']} />);
-        expect(e.getAttribute('hidden')).toBe('');
+        expect(e.getAttribute('hidden')).toBe('foo,bar');
       });
 
-      // this seems like it might mask programmer error, but it's existing behavior.
-      itRenders('boolean prop with object value', async render => {
+      itRenders('hidden prop with object value', async render => {
         const e = await render(<div hidden={{foo: 'bar'}} />);
-        expect(e.getAttribute('hidden')).toBe('');
+        expect(e.getAttribute('hidden')).toBe('[object Object]');
       });
 
-      // this seems like it might mask programmer error, but it's existing behavior.
-      itRenders('boolean prop with non-zero number value', async render => {
+      itRenders('hidden prop with non-zero number value', async render => {
         const e = await render(<div hidden={10} />);
-        expect(e.getAttribute('hidden')).toBe('');
+        expect(e.getAttribute('hidden')).toBe('10');
       });
 
-      // this seems like it might mask programmer error, but it's existing behavior.
-      itRenders('boolean prop with zero value', async render => {
+      itRenders('hidden prop with zero value', async render => {
         const e = await render(<div hidden={0} />);
-        expect(e.getAttribute('hidden')).toBe(null);
+        expect(e.getAttribute('hidden')).toBe('0');
       });
 
-      itRenders('no boolean prop with null value', async render => {
+      itRenders('no hidden prop with null value', async render => {
         const e = await render(<div hidden={null} />);
         expect(e.hasAttribute('hidden')).toBe(false);
       });
 
-      itRenders('no boolean prop with function value', async render => {
+      itRenders('no hidden prop with function value', async render => {
         const e = await render(<div hidden={function () {}} />, 1);
         expect(e.hasAttribute('hidden')).toBe(false);
       });
 
-      itRenders('no boolean prop with symbol value', async render => {
+      itRenders('no hidden prop with symbol value', async render => {
         const e = await render(<div hidden={Symbol('foo')} />, 1);
         expect(e.hasAttribute('hidden')).toBe(false);
       });