From 2351d4afe58234514f170136b2c6ee5d3ff36bad Mon Sep 17 00:00:00 2001
From: Chance Strickland <hi@chance.dev>
Date: Thu, 11 Jun 2026 15:34:07 -0700
Subject: [PATCH 1/4] select: Allow empty select item value for clearing
 selection (#3960)

---
 .changeset/select-clearable-value.md      |  6 ++
 apps/storybook/stories/select.stories.tsx | 54 +++++++++++++
 packages/react/select/src/select.test.tsx | 95 ++++++++++++++++++++++-
 packages/react/select/src/select.tsx      | 25 +++---
 4 files changed, 170 insertions(+), 10 deletions(-)
 create mode 100644 .changeset/select-clearable-value.md

diff --git a/.changeset/select-clearable-value.md b/.changeset/select-clearable-value.md
new file mode 100644
index 000000000..3644eba7d
--- /dev/null
+++ b/.changeset/select-clearable-value.md
@@ -0,0 +1,6 @@
+---
+"@radix-ui/react-select": patch
+"radix-ui": patch
+---
+
+Allow a `Select.Item` with an empty string value to act as a "clear" option. Selecting it resets the selection back to the placeholder, restoring the native `<select>` behavior for optional selects.
diff --git a/apps/storybook/stories/select.stories.tsx b/apps/storybook/stories/select.stories.tsx
index ffacb2a63..ae2415d12 100644
--- a/apps/storybook/stories/select.stories.tsx
+++ b/apps/storybook/stories/select.stories.tsx
@@ -349,6 +349,60 @@ export const NoDefaultValue = () => (
   </div>
 );
 
+export const Clearable = () => (
+  <div
+    style={{
+      display: 'flex',
+      gap: 20,
+      alignItems: 'center',
+      justifyContent: 'center',
+      height: '100vh',
+    }}
+  >
+    <Label>
+      Choose a number (optional):
+      <Select.Root defaultValue="two">
+        <Select.Trigger className={styles.trigger}>
+          <Select.Value placeholder="Pick an option" />
+          <Select.Icon />
+        </Select.Trigger>
+        <Select.Portal>
+          <Select.Content className={styles.content} sideOffset={5}>
+            <Select.Viewport className={styles.viewport}>
+              {/* An item with an empty value resets the selection back to the placeholder */}
+              <Select.Item className={styles.item} value="">
+                <Select.ItemText>None</Select.ItemText>
+                <Select.ItemIndicator className={styles.indicator}>
+                  <TickIcon />
+                </Select.ItemIndicator>
+              </Select.Item>
+              <Select.Item className={styles.item} value="one">
+                <Select.ItemText>One</Select.ItemText>
+                <Select.ItemIndicator className={styles.indicator}>
+                  <TickIcon />
+                </Select.ItemIndicator>
+              </Select.Item>
+              <Select.Item className={styles.item} value="two">
+                <Select.ItemText>Two</Select.ItemText>
+                <Select.ItemIndicator className={styles.indicator}>
+                  <TickIcon />
+                </Select.ItemIndicator>
+              </Select.Item>
+              <Select.Item className={styles.item} value="three">
+                <Select.ItemText>Three</Select.ItemText>
+                <Select.ItemIndicator className={styles.indicator}>
+                  <TickIcon />
+                </Select.ItemIndicator>
+              </Select.Item>
+            </Select.Viewport>
+            <Select.Arrow />
+          </Select.Content>
+        </Select.Portal>
+      </Select.Root>
+    </Label>
+  </div>
+);
+
 export const Typeahead = () => (
   <div
     style={{
diff --git a/packages/react/select/src/select.test.tsx b/packages/react/select/src/select.test.tsx
index 9c4b34e4f..6a140906c 100644
--- a/packages/react/select/src/select.test.tsx
+++ b/packages/react/select/src/select.test.tsx
@@ -1,9 +1,10 @@
 import * as React from 'react';
-import { cleanup, render, screen, waitFor } from '@testing-library/react';
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
 import { afterEach, describe, it, expect } from 'vitest';
 import * as Select from './select';
 
 const PLACEHOLDER_TEXT = 'Pick one';
+const CLEAR_TEXT = 'None';
 
 const SelectTest = (props: React.ComponentProps<typeof Select.Root>) => (
   <Select.Root {...props}>
@@ -25,6 +26,29 @@ const SelectTest = (props: React.ComponentProps<typeof Select.Root>) => (
   </Select.Root>
 );
 
+const SelectClearableTest = (props: React.ComponentProps<typeof Select.Root>) => (
+  <Select.Root {...props}>
+    <Select.Trigger aria-label="Choice">
+      <Select.Value placeholder={PLACEHOLDER_TEXT} />
+    </Select.Trigger>
+    <Select.Portal>
+      <Select.Content position="popper">
+        <Select.Viewport>
+          <Select.Item value="">
+            <Select.ItemText>{CLEAR_TEXT}</Select.ItemText>
+          </Select.Item>
+          <Select.Item value="apple">
+            <Select.ItemText>Apple</Select.ItemText>
+          </Select.Item>
+          <Select.Item value="banana">
+            <Select.ItemText>Banana</Select.ItemText>
+          </Select.Item>
+        </Select.Viewport>
+      </Select.Content>
+    </Select.Portal>
+  </Select.Root>
+);
+
 describe('aria-controls', () => {
   afterEach(cleanup);
 
@@ -47,3 +71,72 @@ describe('aria-controls', () => {
     expect(document.getElementById(content.id)).toBe(content);
   });
 });
+
+describe('clearing an optional value (#2706)', () => {
+  afterEach(cleanup);
+
+  it('allows a `Select.Item` with an empty string value to be rendered', async () => {
+    expect(() => render(<SelectClearableTest defaultOpen />)).not.toThrow();
+    const clearItem = await waitFor(() => screen.getByText(CLEAR_TEXT));
+    expect(clearItem).toBeInTheDocument();
+  });
+
+  it('marks the empty value item as selected when the value is empty', async () => {
+    render(<SelectClearableTest defaultOpen value="" />);
+    const clearItem = await waitFor(() =>
+      screen.getByRole('option', { name: CLEAR_TEXT, hidden: true }),
+    );
+    expect(clearItem).toHaveAttribute('data-state', 'checked');
+  });
+
+  it('shows the placeholder (not the item text) when the empty value item is selected', async () => {
+    render(<SelectClearableTest value="" />);
+    const trigger = screen.getByRole('combobox');
+    expect(trigger).toHaveTextContent(PLACEHOLDER_TEXT);
+    expect(trigger).not.toHaveTextContent(CLEAR_TEXT);
+    expect(trigger).toHaveAttribute('data-placeholder');
+  });
+
+  it('lets the user reset a previously selected value back to the placeholder', async () => {
+    function ControlledSelect() {
+      const [value, setValue] = React.useState<string | undefined>('apple');
+      return <SelectClearableTest value={value} onValueChange={setValue} defaultOpen />;
+    }
+
+    render(<ControlledSelect />);
+    const trigger = screen.getByRole('combobox', { hidden: true });
+
+    // Value starts as "apple" and the trigger reflects it.
+    await waitFor(() => expect(trigger).toHaveTextContent('Apple'));
+    expect(trigger).not.toHaveAttribute('data-placeholder');
+
+    // Selecting the empty value item clears the selection.
+    const clearItem = screen.getByRole('option', { name: CLEAR_TEXT, hidden: true });
+    fireEvent.click(clearItem);
+
+    await waitFor(() => expect(trigger).toHaveTextContent(PLACEHOLDER_TEXT));
+    expect(trigger).not.toHaveTextContent('Apple');
+    expect(trigger).toHaveAttribute('data-placeholder');
+  });
+
+  it('renders a single empty native option when a clear item is provided', async () => {
+    const { container } = render(
+      <form>
+        <SelectClearableTest name="fruit" value="" defaultOpen />
+      </form>,
+    );
+    // Wait for items to register their native options.
+    await waitFor(() => {
+      const nativeSelect = container.querySelector('select');
+      const optionValues = Array.from(nativeSelect?.querySelectorAll('option') ?? []).map(
+        (o) => o.value,
+      );
+      expect(optionValues).toContain('apple');
+    });
+    const nativeSelect = container.querySelector('select');
+    const emptyOptions = Array.from(nativeSelect?.querySelectorAll('option') ?? []).filter(
+      (option) => option.value === '',
+    );
+    expect(emptyOptions).toHaveLength(1);
+  });
+});
diff --git a/packages/react/select/src/select.tsx b/packages/react/select/src/select.tsx
index 4cdacc5ac..14cd1f400 100644
--- a/packages/react/select/src/select.tsx
+++ b/packages/react/select/src/select.tsx
@@ -1379,12 +1379,6 @@ const SelectItem = React.forwardRef<SelectItemElement, SelectItemProps>(
       }
     };
 
-    if (value === '') {
-      throw new Error(
-        'A <Select.Item /> must have a value prop that is not an empty string. This is because the Select value can be set to an empty string to clear the selection and show the placeholder.',
-      );
-    }
-
     return (
       <SelectItemContextProvider
         scope={__scopeSelect}
@@ -1505,8 +1499,13 @@ const SelectItemText = React.forwardRef<SelectItemTextElement, SelectItemTextPro
       <>
         <Primitive.span id={itemContext.textId} {...itemTextProps} ref={composedRefs} />
 
-        {/* Portal the select item text into the trigger value node */}
-        {itemContext.isSelected && context.valueNode && !context.valueNodeHasChildren
+        {/* Portal the select item text into the trigger value node.
+            When the value is empty we show the placeholder instead, so a
+            selected "clear" item (empty value) must not portal its text. */}
+        {itemContext.isSelected &&
+        context.valueNode &&
+        !context.valueNodeHasChildren &&
+        !shouldShowPlaceholder(context.value)
           ? ReactDOM.createPortal(itemTextProps.children, context.valueNode)
           : null}
       </>
@@ -1753,6 +1752,14 @@ const SelectBubbleInput = React.forwardRef<SelectBubbleInputElement, SelectBubbl
     const selectValue = value ?? '';
     const prevValue = usePrevious(selectValue);
 
+    // A consumer may render a `Select.Item` with an empty value to act as a
+    // "clear" option. In that case it already provides a native `<option>` with
+    // an empty value, so we avoid rendering our synthetic placeholder option to
+    // prevent duplicate empty options in the native `select`.
+    const hasEmptyValueOption = Array.from(nativeOptions).some(
+      (option) => (option.props.value ?? '') === '',
+    );
+
     // Bubble value change to parents (e.g form change event)
     React.useEffect(() => {
       const select = ref.current;
@@ -1805,7 +1812,7 @@ const SelectBubbleInput = React.forwardRef<SelectBubbleInputElement, SelectBubbl
         ref={composedRefs}
         defaultValue={selectValue}
       >
-        {shouldShowPlaceholder(value) ? <option value="" /> : null}
+        {shouldShowPlaceholder(value) && !hasEmptyValueOption ? <option value="" /> : null}
         {Array.from(nativeOptions)}
       </Primitive.select>
     );

From 44a40152fdbb4af060bef8ad018e4e6ba018b960 Mon Sep 17 00:00:00 2001
From: Chance Strickland <hi@chance.dev>
Date: Thu, 11 Jun 2026 15:55:01 -0700
Subject: [PATCH 2/4] fix popper regression

---
 .changeset/famous-results-bow.md     |  5 +++++
 packages/react/popper/src/popper.tsx | 12 ++++--------
 2 files changed, 9 insertions(+), 8 deletions(-)
 create mode 100644 .changeset/famous-results-bow.md

diff --git a/.changeset/famous-results-bow.md b/.changeset/famous-results-bow.md
new file mode 100644
index 000000000..6a4fee0ea
--- /dev/null
+++ b/.changeset/famous-results-bow.md
@@ -0,0 +1,5 @@
+---
+"@radix-ui/react-popper": patch
+---
+
+Revert sdfj
diff --git a/packages/react/popper/src/popper.tsx b/packages/react/popper/src/popper.tsx
index 9ad66dfbb..ec35775fe 100644
--- a/packages/react/popper/src/popper.tsx
+++ b/packages/react/popper/src/popper.tsx
@@ -180,7 +180,7 @@ const PopperContent = React.forwardRef<PopperContentElement, PopperContentProps>
       alignOffset = 0,
       arrowPadding = 0,
       avoidCollisions = true,
-      collisionBoundary,
+      collisionBoundary = [],
       collisionPadding: collisionPaddingProp = 0,
       sticky = 'partial',
       hideWhenDetached = false,
@@ -206,16 +206,12 @@ const PopperContent = React.forwardRef<PopperContentElement, PopperContentProps>
         ? collisionPaddingProp
         : { top: 0, right: 0, bottom: 0, left: 0, ...collisionPaddingProp };
 
-    const boundary = collisionBoundary
-      ? Array.isArray(collisionBoundary)
-        ? collisionBoundary
-        : [collisionBoundary]
-      : undefined;
-    const hasExplicitBoundaries = boundary !== undefined && boundary.length > 0;
+    const boundary = Array.isArray(collisionBoundary) ? collisionBoundary : [collisionBoundary];
+    const hasExplicitBoundaries = boundary.length > 0;
 
     const detectOverflowOptions = {
       padding: collisionPadding,
-      boundary: boundary?.filter(isNotNull),
+      boundary: boundary.filter(isNotNull),
       // with `strategy: 'fixed'`, this is the only way to get it to respect boundaries
       altBoundary: hasExplicitBoundaries,
     };

From 751504ea8a8f285772f00d36bbb18be9679a59f3 Mon Sep 17 00:00:00 2001
From: Chance Strickland <hi@chance.dev>
Date: Thu, 11 Jun 2026 15:59:31 -0700
Subject: [PATCH 3/4] re-implement popper fix

---
 .changeset/famous-results-bow.md     |  3 ++-
 packages/react/popper/src/popper.tsx | 14 +++++++++++++-
 2 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/.changeset/famous-results-bow.md b/.changeset/famous-results-bow.md
index 6a4fee0ea..ec103a63a 100644
--- a/.changeset/famous-results-bow.md
+++ b/.changeset/famous-results-bow.md
@@ -1,5 +1,6 @@
 ---
 "@radix-ui/react-popper": patch
+"radix-ui": patch
 ---
 
-Revert sdfj
+Fix regression in popper that caused submenu misalignment when using custom portals
diff --git a/packages/react/popper/src/popper.tsx b/packages/react/popper/src/popper.tsx
index ec35775fe..82b6fe139 100644
--- a/packages/react/popper/src/popper.tsx
+++ b/packages/react/popper/src/popper.tsx
@@ -252,7 +252,19 @@ const PopperContent = React.forwardRef<PopperContentElement, PopperContentProps>
         }),
         arrow && floatingUIarrow({ element: arrow, padding: arrowPadding }),
         transformOrigin({ arrowWidth, arrowHeight }),
-        hideWhenDetached && hide({ strategy: 'referenceHidden', ...detectOverflowOptions }),
+        hideWhenDetached &&
+          hide({
+            strategy: 'referenceHidden',
+            ...detectOverflowOptions,
+            // `hide` detects whether the anchor (reference) is clipped, so when
+            // no explicit `collisionBoundary` is set we fall back to Floating
+            // UI's default clipping ancestors (e.g. a scrollable menu). This
+            // lets an occluded submenu hide once its anchor scrolls out of view
+            // (#3237). The collision/size middlewares deliberately keep the
+            // viewport-based default to avoid clamping content rendered inside
+            // transformed or overflow-clipping portal containers.
+            boundary: hasExplicitBoundaries ? detectOverflowOptions.boundary : undefined,
+          }),
       ],
     });
 

From 45f8b344c0ec303cdd8ff16f796f71dbbd272c84 Mon Sep 17 00:00:00 2001
From: Chance Strickland <hi@chance.dev>
Date: Thu, 11 Jun 2026 16:10:22 -0700
Subject: [PATCH 4/4] add regression tests

---
 apps/storybook/stories/popper.stories.tsx | 92 +++++++++++++++++++++++
 cypress/e2e/Popper.cy.ts                  | 43 +++++++++++
 2 files changed, 135 insertions(+)
 create mode 100644 cypress/e2e/Popper.cy.ts

diff --git a/apps/storybook/stories/popper.stories.tsx b/apps/storybook/stories/popper.stories.tsx
index 765de6e1b..0a98529e3 100644
--- a/apps/storybook/stories/popper.stories.tsx
+++ b/apps/storybook/stories/popper.stories.tsx
@@ -1,4 +1,5 @@
 import * as React from 'react';
+import * as ReactDOM from 'react-dom';
 import { Portal } from 'radix-ui';
 import cx from 'clsx';
 import { Popper } from 'radix-ui/internal';
@@ -195,6 +196,97 @@ export const WithUpdatePositionStrategyAlways = () => {
   );
 };
 
+// Regression test for https://github.com/radix-ui/primitives/pull/3237
+
+// When `hideWhenDetached` is set and no explicit `collisionBoundary` is passed,
+// the `hide` middleware must detect the anchor being clipped by its scroll
+// container, not just the viewport. The anchor below is scrolled out of its
+// container while remaining inside the viewport, so the content should hide.
+export const HideWhenDetachedInScrollContainer = () => {
+  const [container, setContainer] = React.useState<HTMLDivElement | null>(null);
+  return (
+    <div style={{ paddingTop: 300, paddingLeft: 50 }}>
+      <div
+        ref={setContainer}
+        data-testid="scroll-container"
+        style={{ width: 300, height: 200, overflow: 'auto', border: '1px solid black' }}
+      >
+        <div style={{ height: 900, paddingTop: 20 }}>
+          <Popper.Root>
+            <Popper.Anchor
+              data-testid="anchor"
+              className={styles.anchor}
+              style={{ width: 80, height: 40 }}
+            >
+              anchor
+            </Popper.Anchor>
+            {container && (
+              <Portal.Root asChild>
+                <Popper.Content
+                  data-testid="content"
+                  className={styles.content}
+                  side="right"
+                  sideOffset={5}
+                  hideWhenDetached
+                >
+                  content
+                </Popper.Content>
+              </Portal.Root>
+            )}
+          </Popper.Root>
+        </div>
+      </div>
+    </div>
+  );
+};
+
+// When content is rendered via a custom portal into a transformed +
+// overflow-clipping container and no explicit `collisionBoundary` is passed,
+// the available size must be measured against the viewport (the documented
+// default), NOT clamped to the portal host. Here the host is only 120px tall,
+// so a correct `--radix-popper-available-height` should be far larger than
+// that.
+export const AvailableSizeWithCustomPortal = () => {
+  const [host, setHost] = React.useState<HTMLDivElement | null>(null);
+  return (
+    <div style={{ padding: 50 }}>
+      <Popper.Root>
+        <Popper.Anchor
+          data-testid="anchor"
+          className={styles.anchor}
+          style={{ width: 80, height: 40 }}
+        >
+          anchor
+        </Popper.Anchor>
+        {host &&
+          ReactDOM.createPortal(
+            <Popper.Content data-testid="content" className={styles.content} sideOffset={5}>
+              content
+            </Popper.Content>,
+            host,
+          )}
+      </Popper.Root>
+
+      {/* A custom portal host that both establishes a containing block (via
+          `transform`) and clips its children (via `overflow: hidden`), which is
+          what makes Floating UI treat it as a clipping ancestor. */}
+      <div
+        ref={setHost}
+        data-testid="portal-host"
+        style={{
+          position: 'fixed',
+          top: 0,
+          left: 0,
+          width: 120,
+          height: 120,
+          overflow: 'hidden',
+          transform: 'translateZ(0)',
+        }}
+      />
+    </div>
+  );
+};
+
 export const Chromatic = () => {
   const [scrollContainer1, setScrollContainer1] = React.useState<HTMLDivElement | null>(null);
   const [scrollContainer2, setScrollContainer2] = React.useState<HTMLDivElement | null>(null);
diff --git a/cypress/e2e/Popper.cy.ts b/cypress/e2e/Popper.cy.ts
new file mode 100644
index 000000000..d7176c4da
--- /dev/null
+++ b/cypress/e2e/Popper.cy.ts
@@ -0,0 +1,43 @@
+// `Popper` stories live under the `Utilities/*` namespace, so they can't be
+// reached through the `components-` prefixed `cy.visitStory` helper.
+function visitPopperStory(storyName: string) {
+  return cy.visit(`iframe.html?id=utilities-popper--${storyName}`);
+}
+
+describe('Popper', () => {
+  // Regression test for https://github.com/radix-ui/primitives/pull/3237
+  describe('given hideWhenDetached and no explicit collisionBoundary', () => {
+    beforeEach(() => {
+      visitPopperStory('hide-when-detached-in-scroll-container');
+    });
+
+    it('hides the content when the anchor is clipped by its scroll container but still within the viewport', () => {
+      cy.findByTestId('content').should('be.visible');
+
+      // Scroll the anchor out of the (200px tall) scroll container while keeping
+      // it on screen. Detach detection must fall back to clipping ancestors, not
+      // the viewport, otherwise the content would incorrectly stay visible.
+      cy.findByTestId('scroll-container').scrollTo(0, 200);
+
+      cy.findByTestId('content').should('not.be.visible');
+    });
+  });
+
+  // Regression test for the 1.3.0 custom-portal regression.
+  describe('given content in a transformed, overflow-clipping custom portal host', () => {
+    beforeEach(() => {
+      visitPopperStory('available-size-with-custom-portal');
+    });
+
+    it('measures available size against the viewport, not the portal host', () => {
+      // The portal host is only 120px tall. If the collision/size middlewares
+      // clamped to it (the regression), available height would be <= ~120px.
+      cy.get('[data-radix-popper-content-wrapper]').should(($wrapper) => {
+        const availableHeight = parseFloat(
+          getComputedStyle($wrapper[0]).getPropertyValue('--radix-popper-available-height'),
+        );
+        expect(availableHeight).to.be.greaterThan(300);
+      });
+    });
+  });
+});