@base-ui/react 1.6.0 → 1.8.0

package/docs/react/components/combobox.md

@@ -587,28 +587,613 @@ import { Combobox } from '@base-ui/react/combobox';
 </Combobox.Root>;
 ```
 
-## TypeScript
+## Item values
+
+Each `<Combobox.Item>` takes a `value` prop identifying it. Pass the item being rendered:
+
+```jsx title="Using item objects as values"
+<Combobox.List>
+  {(item) => (
+    <Combobox.Item key={item.id} value={item}>
+      {item.label}
+    </Combobox.Item>
+  )}
+</Combobox.List>
+```
+
+That item is what `value`, `defaultValue`, and `onValueChange` receive. To store IDs instead, see [Value selection with IDs](/react/components/combobox.md).
+
+## Examples
+
+### Typed wrapper component
+
+The following example shows a typed wrapper around the Combobox component with correct type inference and type safety:
+
+```tsx title="Specifying generic type parameters"
+import * as React from 'react';
+import { Combobox } from '@base-ui/react/combobox';
+
+export function MyCombobox<Value, Multiple extends boolean | undefined = false, Item = Value>(
+  props: Combobox.Root.Props<Value, Multiple, Item>,
+): React.JSX.Element {
+  return <Combobox.Root {...props}>{/* ... */}</Combobox.Root>;
+}
+```
+
+The third `Item` type parameter is what lets the wrapper accept a `Combobox.createItems()` collection, whose rendered item type differs from its selection value. Omit it and a collection infers `Value` as the source item type, surfacing an error on `defaultValue` rather than on `items`.
+
+### Value selection with IDs
+
+When your app stores IDs rather than item objects, use `Combobox.createItems` with `getValue` and `getLabel` to derive each item's selection value and display label.
+
+With static data, create the collection at module scope. The accessor parameters are inferred from `users`. Pass the derived ID to the `value` prop of `<Combobox.Item>`, not the item being rendered:
+
+```jsx title="Using item IDs as values"
+const items = Combobox.createItems(users, {
+  getValue: (user) => user.id,
+  getLabel: (user) => user.name,
+});
+
+<Combobox.Root items={items}>
+  <Combobox.List>
+    {(user) => (
+      <Combobox.Item key={user.id} value={user.id}>
+        {user.name}
+      </Combobox.Item>
+    )}
+  </Combobox.List>
+</Combobox.Root>;
+```
+
+Selection props and events use the derived IDs, while list rendering continues to receive the original items. The derived label is also used for filtering and typeahead.
+
+When the data is loaded or replaced at runtime, memoize the collection on it so that it is rebuilt only when the data changes:
+
+```jsx title="Creating a collection from dynamic data"
+const items = React.useMemo(
+  () =>
+    Combobox.createItems(users, {
+      getValue: (user) => user.id,
+      getLabel: (user) => user.name,
+    }),
+  [users],
+);
+```
+
+## Demo
+
+### Tailwind
+
+This example shows how to implement the component using Tailwind CSS.
+
+```tsx
+/* index.tsx */
+'use client';
+import * as React from 'react';
+import { Combobox } from '@base-ui/react/combobox';
+
+export default function ExampleCreateItemsCombobox() {
+  const id = React.useId();
+
+  return (
+    <Combobox.Root items={items} defaultValue="banana">
+      <div className="relative flex flex-col gap-1 text-sm leading-5 font-bold text-neutral-950 dark:text-white">
+        <label htmlFor={id}>Choose a fruit</label>
+        <Combobox.InputGroup className="relative h-8 w-56 border border-neutral-950 bg-white dark:bg-neutral-950 focus-within:outline-2 focus-within:-outline-offset-1 focus-within:outline-neutral-950 dark:focus-within:outline-white dark:border-white [&>input]:pr-[calc(0.5rem+2rem)] has-[.combobox-clear]:[&>input]:pr-[calc(0.5rem+2rem*2)]">
+          <Combobox.Input
+            placeholder="e.g. Apple"
+            id={id}
+            className="h-full w-full border-0 bg-white pl-2 dark:bg-neutral-950 text-sm any-pointer-coarse:text-base font-normal text-neutral-950 outline-none placeholder:text-neutral-500 dark:placeholder:text-neutral-400 dark:text-white"
+          />
+          <div className="absolute right-0 bottom-0 flex h-full items-center justify-center text-neutral-500 dark:text-neutral-400">
+            <Combobox.Clear
+              className="combobox-clear flex h-full w-6 items-center justify-center border-0 bg-transparent p-0 text-neutral-950 dark:text-white"
+              aria-label="Clear selection"
+            >
+              <XIcon />
+            </Combobox.Clear>
+            <Combobox.Trigger
+              className="flex h-full w-6 items-center justify-center border-0 bg-transparent p-0 text-neutral-950 dark:text-white"
+              aria-label="Open popup"
+            >
+              <CaretDownIcon />
+            </Combobox.Trigger>
+          </div>
+        </Combobox.InputGroup>
+      </div>
+
+      <Combobox.Portal>
+        <Combobox.Positioner className="outline-none" sideOffset={4}>
+          <Combobox.Popup className="w-[var(--anchor-width)] max-w-[var(--available-width)] origin-[var(--transform-origin)] border border-neutral-950 bg-white text-neutral-950 shadow-[0.25rem_0.25rem_0_rgb(0_0_0_/_12%)] transition-[scale,opacity] duration-100 data-starting-style:scale-95 data-starting-style:opacity-0 data-ending-style:scale-95 data-ending-style:opacity-0 dark:border-white dark:bg-neutral-950 dark:text-white dark:shadow-none">
+            <Combobox.Empty>
+              <div className="py-4 pr-4 pl-2 text-sm leading-4 text-neutral-500 dark:text-neutral-400">
+                No fruits found.
+              </div>
+            </Combobox.Empty>
+            <Combobox.List className="max-h-[min(22.5rem,var(--available-height))] overflow-y-auto overscroll-contain py-1 scroll-py-1 outline-0 data-empty:p-0">
+              {(item) => (
+                <Combobox.Item
+                  key={item.id}
+                  value={item.id}
+                  className="grid cursor-default grid-cols-[1rem_1fr] items-center gap-2 p-2 text-sm leading-4 outline-none select-none data-highlighted:relative data-highlighted:z-0 data-highlighted:text-white data-highlighted:before:absolute data-highlighted:before:inset-0 data-highlighted:before:z-[-1] data-highlighted:before:bg-neutral-950 dark:data-highlighted:text-neutral-950 dark:data-highlighted:before:bg-white"
+                >
+                  <Combobox.ItemIndicator className="col-start-1">
+                    <CheckIcon />
+                  </Combobox.ItemIndicator>
+                  <span className="col-start-2">{item.name}</span>
+                </Combobox.Item>
+              )}
+            </Combobox.List>
+          </Combobox.Popup>
+        </Combobox.Positioner>
+      </Combobox.Portal>
+    </Combobox.Root>
+  );
+}
+
+function CheckIcon(props: React.ComponentProps<'svg'>) {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      {...props}
+      style={{ display: 'block', ...props.style }}
+    >
+      <path d="m2.5 8.5 4 4 7-9" />
+    </svg>
+  );
+}
+
+function XIcon(props: React.ComponentProps<'svg'>) {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeLinecap="square"
+      strokeLinejoin="round"
+      {...props}
+      style={{ display: 'block', ...props.style }}
+    >
+      <path d="m4.5 4.5 7 7m-7 0 7-7" />
+    </svg>
+  );
+}
+
+function CaretDownIcon(props: React.ComponentProps<'svg'>) {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="currentColor"
+      {...props}
+      style={{ display: 'block', ...props.style }}
+    >
+      <path d="M12 6H4l4 4.5z" />
+    </svg>
+  );
+}
+
+interface Fruit {
+  id: string;
+  name: string;
+}
+
+const fruits: Fruit[] = [
+  { id: 'apple', name: 'Apple' },
+  { id: 'banana', name: 'Banana' },
+  { id: 'orange', name: 'Orange' },
+  { id: 'pineapple', name: 'Pineapple' },
+  { id: 'grape', name: 'Grape' },
+  { id: 'mango', name: 'Mango' },
+  { id: 'strawberry', name: 'Strawberry' },
+  { id: 'blueberry', name: 'Blueberry' },
+  { id: 'raspberry', name: 'Raspberry' },
+  { id: 'blackberry', name: 'Blackberry' },
+  { id: 'cherry', name: 'Cherry' },
+  { id: 'peach', name: 'Peach' },
+  { id: 'pear', name: 'Pear' },
+  { id: 'plum', name: 'Plum' },
+  { id: 'kiwi', name: 'Kiwi' },
+  { id: 'watermelon', name: 'Watermelon' },
+];
+
+const items = Combobox.createItems(fruits, {
+  getValue: (fruit) => fruit.id,
+  getLabel: (fruit) => fruit.name,
+});
+```
+
+### CSS Modules
+
+This example shows how to implement the component using CSS Modules.
+
+```css
+/* index.module.css */
+.InputGroup {
+  box-sizing: border-box;
+  position: relative;
+  width: 14rem;
+  height: 2rem;
+  border: 1px solid oklch(14.5% 0 0deg);
+  background-color: white;
+
+  @media (prefers-color-scheme: dark) {
+    border: 1px solid white;
+    background-color: oklch(14.5% 0 0deg);
+  }
+
+  &:focus-within {
+    outline: 2px solid oklch(14.5% 0 0deg);
+    outline-offset: -1px;
+
+    @media (prefers-color-scheme: dark) {
+      outline-color: white;
+    }
+  }
+
+  &:has(.Clear) .Input {
+    padding: 0 calc(0.5rem + 2rem * 2) 0 0.5rem;
+  }
+}
+
+.Input {
+  box-sizing: border-box;
+  padding: 0 calc(0.5rem + 2rem) 0 0.5rem;
+  margin: 0;
+  border: none;
+  border-radius: 0;
+  width: 100%;
+  height: 100%;
+  font-family: inherit;
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  font-weight: 400;
+  background-color: white;
+  color: oklch(14.5% 0 0deg);
+
+  @media (any-pointer: coarse) {
+    font-size: 1rem;
+    line-height: 1.5rem;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    background-color: oklch(14.5% 0 0deg);
+    color: white;
+  }
+
+  &::placeholder {
+    color: oklch(55.6% 0 0deg);
+
+    @media (prefers-color-scheme: dark) {
+      color: oklch(70.8% 0 0deg);
+    }
+  }
+
+  &:focus {
+    outline: none;
+  }
+}
+
+.Label {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  font-weight: 700;
+  color: oklch(14.5% 0 0deg);
+  position: relative;
+
+  @media (prefers-color-scheme: dark) {
+    color: white;
+  }
+}
+
+.ActionButtons {
+  box-sizing: border-box;
+  position: absolute;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  bottom: 0;
+  height: 100%;
+  right: 0;
+  border: none;
+  color: oklch(55.6% 0 0deg);
+  padding: 0;
+
+  @media (prefers-color-scheme: dark) {
+    color: oklch(70.8% 0 0deg);
+  }
+}
+
+.Trigger,
+.Clear {
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.5rem;
+  height: 100%;
+  color: oklch(14.5% 0 0deg);
+  border: none;
+  padding: 0;
+  background: none;
+
+  @media (prefers-color-scheme: dark) {
+    color: white;
+  }
+}
+
+.Positioner {
+  outline: 0;
+}
+
+.Popup {
+  box-sizing: border-box;
+  background-color: white;
+  color: oklch(14.5% 0 0deg);
+  width: var(--anchor-width);
+  max-width: var(--available-width);
+  transition:
+    opacity 0.1s,
+    transform 0.1s;
+  transform-origin: var(--transform-origin);
+
+  border: 1px solid oklch(14.5% 0 0deg);
+  box-shadow: 0.25rem 0.25rem 0 rgb(0 0 0 / 12%);
+
+  @media (prefers-color-scheme: dark) {
+    background-color: oklch(14.5% 0 0deg);
+    color: white;
+    border: 1px solid white;
+    box-shadow: none;
+  }
+
+  &[data-starting-style],
+  &[data-ending-style] {
+    opacity: 0;
+    transform: scale(0.95);
+  }
+}
+
+.List {
+  box-sizing: border-box;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  padding-block: 0.25rem;
+  scroll-padding-block: 0.25rem;
+  outline: 0;
+  max-height: min(22.5rem, var(--available-height));
+
+  &[data-empty] {
+    padding: 0;
+  }
+}
+
+.Item {
+  box-sizing: border-box;
+  outline: 0;
+  cursor: default;
+  -webkit-user-select: none;
+  user-select: none;
+  padding-block: 0.5rem;
+  padding-left: 0.5rem;
+  padding-right: 0.5rem;
+  display: grid;
+  gap: 0.5rem;
+  align-items: center;
+  grid-template-columns: 1rem 1fr;
+  font-size: 0.875rem;
+  line-height: 1rem;
+
+  &[data-highlighted] {
+    z-index: 0;
+    position: relative;
+    color: white;
+
+    @media (prefers-color-scheme: dark) {
+      color: oklch(14.5% 0 0deg);
+    }
+  }
+
+  &[data-highlighted]::before {
+    content: '';
+    z-index: -1;
+    position: absolute;
+    inset-block: 0;
+    inset-inline: 0;
+    background-color: oklch(14.5% 0 0deg);
+
+    @media (prefers-color-scheme: dark) {
+      background-color: white;
+    }
+  }
+}
+
+.ItemText {
+  grid-column-start: 2;
+}
+
+.ItemIndicator {
+  grid-column-start: 1;
+}
+
+.Empty {
+  box-sizing: border-box;
+  padding: 1rem 1rem 1rem 0.5rem;
+  font-size: 0.875rem;
+  line-height: 1rem;
+  color: oklch(55.6% 0 0deg);
+
+  @media (prefers-color-scheme: dark) {
+    color: oklch(70.8% 0 0deg);
+  }
+}
+```
+
+```tsx
+/* index.tsx */
+'use client';
+import * as React from 'react';
+import { Combobox } from '@base-ui/react/combobox';
+import styles from './index.module.css';
+
+export default function ExampleCreateItemsCombobox() {
+  const id = React.useId();
+
+  return (
+    <Combobox.Root items={items} defaultValue="banana">
+      <div className={styles.Label}>
+        <label htmlFor={id}>Choose a fruit</label>
+        <Combobox.InputGroup className={styles.InputGroup}>
+          <Combobox.Input placeholder="e.g. Apple" id={id} className={styles.Input} />
+          <div className={styles.ActionButtons}>
+            <Combobox.Clear className={styles.Clear} aria-label="Clear selection">
+              <XIcon />
+            </Combobox.Clear>
+            <Combobox.Trigger className={styles.Trigger} aria-label="Open popup">
+              <CaretDownIcon />
+            </Combobox.Trigger>
+          </div>
+        </Combobox.InputGroup>
+      </div>
+
+      <Combobox.Portal>
+        <Combobox.Positioner className={styles.Positioner} sideOffset={4}>
+          <Combobox.Popup className={styles.Popup}>
+            <Combobox.Empty>
+              <div className={styles.Empty}>No fruits found.</div>
+            </Combobox.Empty>
+            <Combobox.List className={styles.List}>
+              {(item) => (
+                <Combobox.Item key={item.id} value={item.id} className={styles.Item}>
+                  <Combobox.ItemIndicator className={styles.ItemIndicator}>
+                    <CheckIcon />
+                  </Combobox.ItemIndicator>
+                  <span className={styles.ItemText}>{item.name}</span>
+                </Combobox.Item>
+              )}
+            </Combobox.List>
+          </Combobox.Popup>
+        </Combobox.Positioner>
+      </Combobox.Portal>
+    </Combobox.Root>
+  );
+}
 
-Combobox infers the item type from the `defaultValue` or `value` props passed to `<Combobox.Root>`.
-The type of items held in the `items` array must also match the `value` prop type passed to `<Combobox.Item>`.
+function CheckIcon(props: React.ComponentProps<'svg'>) {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      {...props}
+      style={{ display: 'block', ...props.style }}
+    >
+      <path d="m2.5 8.5 4 4 7-9" />
+    </svg>
+  );
+}
 
-## Examples
+function XIcon(props: React.ComponentProps<'svg'>) {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeLinecap="square"
+      strokeLinejoin="round"
+      {...props}
+      style={{ display: 'block', ...props.style }}
+    >
+      <path d="m4.5 4.5 7 7m-7 0 7-7" />
+    </svg>
+  );
+}
 
-### Typed wrapper component
+function CaretDownIcon(props: React.ComponentProps<'svg'>) {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="currentColor"
+      {...props}
+      style={{ display: 'block', ...props.style }}
+    >
+      <path d="M12 6H4l4 4.5z" />
+    </svg>
+  );
+}
 
-The following example shows a typed wrapper around the Combobox component with correct type inference and type safety:
+interface Fruit {
+  id: string;
+  name: string;
+}
 
-```tsx title="Specifying generic type parameters"
-import * as React from 'react';
-import { Combobox } from '@base-ui/react/combobox';
+const fruits: Fruit[] = [
+  { id: 'apple', name: 'Apple' },
+  { id: 'banana', name: 'Banana' },
+  { id: 'orange', name: 'Orange' },
+  { id: 'pineapple', name: 'Pineapple' },
+  { id: 'grape', name: 'Grape' },
+  { id: 'mango', name: 'Mango' },
+  { id: 'strawberry', name: 'Strawberry' },
+  { id: 'blueberry', name: 'Blueberry' },
+  { id: 'raspberry', name: 'Raspberry' },
+  { id: 'blackberry', name: 'Blackberry' },
+  { id: 'cherry', name: 'Cherry' },
+  { id: 'peach', name: 'Peach' },
+  { id: 'pear', name: 'Pear' },
+  { id: 'plum', name: 'Plum' },
+  { id: 'kiwi', name: 'Kiwi' },
+  { id: 'watermelon', name: 'Watermelon' },
+];
 
-export function MyCombobox<Value, Multiple extends boolean | undefined = false>(
-  props: Combobox.Root.Props<Value, Multiple>,
-): React.JSX.Element {
-  return <Combobox.Root {...props}>{/* ... */}</Combobox.Root>;
-}
+const items = Combobox.createItems(fruits, {
+  getValue: (fruit) => fruit.id,
+  getLabel: (fruit) => fruit.name,
+});
+```
+
+As a rule of thumb, use primitive items for simple lists, object values when the selected record is useful application state, and `createItems()` when selection should use a stable primitive ID while rendering and filtering still use object records.
+
+Stable IDs preserve item matching when an async data library replaces row objects during a refetch. With object values, use `isItemEqualToValue` to compare their IDs instead.
+
+When results are filtered externally (for example, by a server-side search), `items` represents records known to the app, while `filteredItems` represents the current result window displayed in the popup. Pass source items rather than derived values to `filteredItems`, preserving the flat or grouped structure of `items`:
+
+```tsx title="Displaying a window of async results"
+const items = React.useMemo(
+  () =>
+    Combobox.createItems(knownUsers, {
+      getValue: (user) => user.id,
+      getLabel: (user) => user.name,
+    }),
+  [knownUsers],
+);
+
+<Combobox.Root
+  items={items}
+  filteredItems={searchResults}
+  value={selectedUserId}
+  onValueChange={setSelectedUserId}
+/>;
 ```
 
+Include the selected user's record in `knownUsers` so its label remains available when it is outside `searchResults`. Alternatively, provide `itemToStringLabel` when the label can be derived from the selected value alone.
+
 ### Multiple select
 
 The combobox can allow multiple selections by adding the `multiple` prop to `<Combobox.Root>`.
@@ -639,34 +1224,41 @@ export default function ExampleMultipleCombobox() {
           Programming languages
         </label>
         <Combobox.InputGroup className="flex min-h-8 w-64 cursor-text flex-wrap items-center gap-0.5 border border-neutral-950 bg-white dark:bg-neutral-950 px-2 py-1 focus-within:outline-2 focus-within:-outline-offset-1 focus-within:outline-neutral-950 dark:focus-within:outline-white has-[button]:px-1 dark:border-white min-[32rem]:w-[22rem]">
-          <Combobox.Chips className="flex w-full flex-wrap items-center gap-1">
-            <Combobox.Value>
-              {(value: ProgrammingLanguage[]) => (
-                <React.Fragment>
-                  {value.map((language) => (
-                    <Combobox.Chip
-                      key={language.id}
-                      className="group flex min-h-[calc(1.5rem-2px)] cursor-default items-center gap-1 overflow-hidden bg-neutral-100 py-0 pr-[0.2rem] pl-[0.4rem] text-sm leading-none text-neutral-950 outline-none focus-within:bg-neutral-950 focus-within:text-white [@media(hover:hover)]:data-highlighted:bg-neutral-950 [@media(hover:hover)]:data-highlighted:text-white dark:bg-neutral-800 dark:text-white dark:focus-within:bg-white dark:focus-within:text-neutral-950 dark:[@media(hover:hover)]:data-highlighted:bg-white dark:[@media(hover:hover)]:data-highlighted:text-neutral-950"
-                      aria-label={language.value}
+          <Combobox.Value>
+            {(value: ProgrammingLanguage[]) => (
+              <Combobox.Chips
+                className="flex w-full flex-wrap items-center gap-1"
+                aria-label={value.length > 0 ? 'Selected languages' : undefined}
+              >
+                {value.map((language) => (
+                  <Combobox.Chip
+                    key={language.id}
+                    className="group flex min-h-[calc(1.5rem-2px)] cursor-default items-center gap-1 overflow-hidden bg-neutral-100 py-0 pr-[0.2rem] pl-[0.4rem] text-sm leading-none text-neutral-950 outline-none focus-within:bg-neutral-950 focus-within:text-white [@media(hover:hover)]:data-highlighted:bg-neutral-950 [@media(hover:hover)]:data-highlighted:text-white dark:bg-neutral-800 dark:text-white dark:focus-within:bg-white dark:focus-within:text-neutral-950 dark:[@media(hover:hover)]:data-highlighted:bg-white dark:[@media(hover:hover)]:data-highlighted:text-neutral-950"
+                    aria-label={language.value}
+                    aria-description="Press Backspace or Delete to remove"
+                  >
+                    {language.value}
+                    <Combobox.ChipRemove
+                      className="flex size-4 items-center justify-center border-0 bg-transparent p-0 text-inherit hover:bg-neutral-200 group-focus-within:hover:bg-neutral-700 dark:hover:bg-neutral-700 dark:group-focus-within:hover:bg-neutral-200"
+                      aria-label={`Remove ${language.value}`}
                     >
-                      {language.value}
-                      <Combobox.ChipRemove
-                        className="flex size-4 items-center justify-center border-0 bg-transparent p-0 text-inherit hover:bg-neutral-200 group-focus-within:hover:bg-neutral-700 dark:hover:bg-neutral-700 dark:group-focus-within:hover:bg-neutral-200"
-                        aria-label={`Remove ${language.value}`}
-                      >
-                        <XIcon />
-                      </Combobox.ChipRemove>
-                    </Combobox.Chip>
-                  ))}
-                  <Combobox.Input
-                    id={id}
-                    placeholder={value.length > 0 ? '' : 'e.g. TypeScript'}
-                    className="h-[calc(1.5rem-2px)] min-w-12 flex-1 border-0 bg-white p-0 text-sm any-pointer-coarse:text-base dark:bg-neutral-950 font-normal text-neutral-950 outline-none placeholder:text-neutral-500 dark:placeholder:text-neutral-400 dark:text-white"
-                  />
-                </React.Fragment>
-              )}
-            </Combobox.Value>
-          </Combobox.Chips>
+                      <XIcon />
+                    </Combobox.ChipRemove>
+                  </Combobox.Chip>
+                ))}
+                <Combobox.Input
+                  id={id}
+                  placeholder={value.length > 0 ? '' : 'e.g. TypeScript'}
+                  aria-description={
+                    value.length > 0
+                      ? `${value.length} selected. From the start of the input, press Left Arrow to focus the selected items`
+                      : undefined
+                  }
+                  className="h-[calc(1.5rem-2px)] min-w-12 flex-1 border-0 bg-white p-0 text-sm any-pointer-coarse:text-base dark:bg-neutral-950 font-normal text-neutral-950 outline-none placeholder:text-neutral-500 dark:placeholder:text-neutral-400 dark:text-white"
+                />
+              </Combobox.Chips>
+            )}
+          </Combobox.Value>
         </Combobox.InputGroup>
       </div>
 
@@ -1090,34 +1682,41 @@ export default function ExampleMultipleCombobox() {
           Programming languages
         </label>
         <Combobox.InputGroup className={styles.InputGroup}>
-          <Combobox.Chips className={styles.Chips}>
-            <Combobox.Value>
-              {(value: ProgrammingLanguage[]) => (
-                <React.Fragment>
-                  {value.map((language) => (
-                    <Combobox.Chip
-                      key={language.id}
-                      className={styles.Chip}
-                      aria-label={language.value}
+          <Combobox.Value>
+            {(value: ProgrammingLanguage[]) => (
+              <Combobox.Chips
+                className={styles.Chips}
+                aria-label={value.length > 0 ? 'Selected languages' : undefined}
+              >
+                {value.map((language) => (
+                  <Combobox.Chip
+                    key={language.id}
+                    className={styles.Chip}
+                    aria-label={language.value}
+                    aria-description="Press Backspace or Delete to remove"
+                  >
+                    {language.value}
+                    <Combobox.ChipRemove
+                      className={styles.ChipRemove}
+                      aria-label={`Remove ${language.value}`}
                     >
-                      {language.value}
-                      <Combobox.ChipRemove
-                        className={styles.ChipRemove}
-                        aria-label={`Remove ${language.value}`}
-                      >
-                        <XIcon />
-                      </Combobox.ChipRemove>
-                    </Combobox.Chip>
-                  ))}
-                  <Combobox.Input
-                    id={id}
-                    placeholder={value.length > 0 ? '' : 'e.g. TypeScript'}
-                    className={styles.Input}
-                  />
-                </React.Fragment>
-              )}
-            </Combobox.Value>
-          </Combobox.Chips>
+                      <XIcon />
+                    </Combobox.ChipRemove>
+                  </Combobox.Chip>
+                ))}
+                <Combobox.Input
+                  id={id}
+                  placeholder={value.length > 0 ? '' : 'e.g. TypeScript'}
+                  aria-description={
+                    value.length > 0
+                      ? `${value.length} selected. From the start of the input, press Left Arrow to focus the selected items`
+                      : undefined
+                  }
+                  className={styles.Input}
+                />
+              </Combobox.Chips>
+            )}
+          </Combobox.Value>
         </Combobox.InputGroup>
       </div>
 
@@ -1198,6 +1797,9 @@ const langs: ProgrammingLanguage[] = [
 ];
 ```
 
+In order for screen readers to announce how to reach and remove the chips, add `aria-description` to `<Combobox.Chip>` and `<Combobox.Input>`, alongside the `aria-label` on `<Combobox.Chips>` and `<Combobox.ChipRemove>`.
+Base UI does not ship these strings. Translate them together with the rest of your interface.
+
 Visible chips can be limited by slicing the selected values rendered in `<Combobox.Value>`:
 
 ```tsx title="Limiting visible chips"
@@ -1212,7 +1814,7 @@ const CHIP_LIMIT = 3;
     return (
       <>
         {visibleValue.map((item) => (
-          <Combobox.Chip key={item}>
+          <Combobox.Chip key={item} aria-description="Press Backspace or Delete to remove">
             {item}
             <Combobox.ChipRemove aria-label={`Remove ${item}`} />
           </Combobox.Chip>
@@ -1220,13 +1822,53 @@ const CHIP_LIMIT = 3;
         {/* @highlight-start */}
         {hiddenCount > 0 && <span>{`+${hiddenCount} more`}</span>}
         {/* @highlight-end */}
-        <Combobox.Input />
+        <Combobox.Input
+          aria-description={
+            selectedValue.length > 0
+              ? `${selectedValue.length} selected. From the start of the input, press Left Arrow to focus the selected items`
+              : undefined
+          }
+        />
       </>
     );
   }}
 </Combobox.Value>;
 ```
 
+#### Keeping the filter after selection
+
+In `multiple` mode, selecting an item clears the typed filter and closes the popup when the input is rendered outside it. To let users pick several results from one query, cancel the relevant change request.
+
+Which request to cancel depends on the input's placement. When the input is outside the popup, cancel the `item-press` close request in `onOpenChange`. When it is inside, cancel the clear request in `onInputValueChange`, marked with `eventDetails.isItemPress`.
+
+```jsx title="Input outside the popup"
+<Combobox.Root
+  multiple
+  onOpenChange={(open, eventDetails) => {
+    if (!open && eventDetails.reason === 'item-press') {
+      eventDetails.cancel();
+    }
+  }}
+>
+  {/* ... */}
+</Combobox.Root>
+```
+
+```jsx title="Input inside the popup"
+<Combobox.Root
+  multiple
+  onInputValueChange={(value, eventDetails) => {
+    if (eventDetails.isItemPress) {
+      eventDetails.cancel();
+    }
+  }}
+>
+  {/* ... */}
+</Combobox.Root>
+```
+
+The typed filter still resets once the popup closes.
+
 ### Input inside popup
 
 `<Combobox.Input>` can be rendered inside `<Combobox.Popup>` to create a searchable select popup.
@@ -1250,7 +1892,7 @@ export default function ExamplePopoverCombobox() {
         <Combobox.Label className="cursor-default text-sm leading-5 font-bold text-neutral-950 dark:text-white">
           Country
         </Combobox.Label>
-        <Combobox.Trigger className="flex h-8 min-w-40 cursor-default items-center justify-between gap-3 border border-neutral-950 bg-white pl-2 pr-1 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 select-none hover:bg-neutral-100 active:bg-neutral-200 data-popup-open:bg-neutral-100 data-placeholder:text-neutral-500 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:data-placeholder:text-neutral-400 dark:focus-visible:outline-white dark:border-white dark:bg-neutral-950 dark:text-white dark:hover:bg-neutral-800 dark:active:bg-neutral-700 dark:data-popup-open:bg-neutral-800">
+        <Combobox.Trigger className="flex h-8 min-w-40 cursor-default items-center justify-between gap-3 border border-neutral-950 bg-white pl-2 pr-1 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 select-none hover:bg-neutral-100 active:bg-neutral-200 data-pressed:bg-neutral-100 data-placeholder:text-neutral-500 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:data-placeholder:text-neutral-400 dark:focus-visible:outline-white dark:border-white dark:bg-neutral-950 dark:text-white dark:hover:bg-neutral-800 dark:active:bg-neutral-700 dark:data-pressed:bg-neutral-800">
           <Combobox.Value placeholder="Select country" />
           <Combobox.Icon className="text-neutral-950 dark:text-white">
             <CaretUpDownIcon />
@@ -1605,7 +2247,7 @@ This example shows how to implement the component using CSS Modules.
     }
   }
 
-  &[data-popup-open] {
+  &[data-pressed] {
     background-color: oklch(97% 0 0deg);
 
     @media (prefers-color-scheme: dark) {
@@ -2810,6 +3452,7 @@ export default function ExampleAsyncSingleCombobox() {
     <Combobox.Root
       items={items}
       itemToStringLabel={(user: DirectoryUser) => user.name}
+      isItemEqualToValue={(item, value) => item.id === value.id}
       filter={null}
       onOpenChangeComplete={(open) => {
         if (!open && selectedValue) {
@@ -3466,6 +4109,7 @@ export default function ExampleAsyncSingleCombobox() {
     <Combobox.Root
       items={items}
       itemToStringLabel={(user: DirectoryUser) => user.name}
+      isItemEqualToValue={(item, value) => item.id === value.id}
       filter={null}
       onOpenChangeComplete={(open) => {
         if (!open && selectedValue) {
@@ -3830,6 +4474,7 @@ export default function ExampleAsyncMultipleCombobox() {
     <Combobox.Root
       items={items}
       itemToStringLabel={(user: DirectoryUser) => user.name}
+      isItemEqualToValue={(item, value) => item.id === value.id}
       multiple
       filter={null}
       onOpenChangeComplete={(open) => {
@@ -3893,34 +4538,41 @@ export default function ExampleAsyncMultipleCombobox() {
           Assign reviewers
         </label>
         <Combobox.InputGroup className="flex min-h-8 w-64 cursor-text flex-wrap items-center gap-0.5 border border-neutral-950 bg-white dark:bg-neutral-950 px-2 py-1 focus-within:outline-2 focus-within:-outline-offset-1 focus-within:outline-neutral-950 dark:focus-within:outline-white has-[button]:px-1 dark:border-white min-[32rem]:w-[22rem]">
-          <Combobox.Chips className="flex w-full flex-wrap items-center gap-1">
-            <Combobox.Value>
-              {(value: DirectoryUser[]) => (
-                <React.Fragment>
-                  {value.map((user) => (
-                    <Combobox.Chip
-                      key={user.id}
-                      className="group flex min-h-[calc(1.5rem-2px)] cursor-default items-center gap-1 overflow-hidden bg-neutral-100 py-0 pr-[0.2rem] pl-[0.4rem] text-sm leading-none text-neutral-950 outline-none focus-within:bg-neutral-950 focus-within:text-white [@media(hover:hover)]:data-highlighted:bg-neutral-950 [@media(hover:hover)]:data-highlighted:text-white dark:bg-neutral-800 dark:text-white dark:focus-within:bg-white dark:focus-within:text-neutral-950 dark:[@media(hover:hover)]:data-highlighted:bg-white dark:[@media(hover:hover)]:data-highlighted:text-neutral-950"
-                      aria-label={user.name}
+          <Combobox.Value>
+            {(value: DirectoryUser[]) => (
+              <Combobox.Chips
+                className="flex w-full flex-wrap items-center gap-1"
+                aria-label={value.length > 0 ? 'Selected reviewers' : undefined}
+              >
+                {value.map((user) => (
+                  <Combobox.Chip
+                    key={user.id}
+                    className="group flex min-h-[calc(1.5rem-2px)] cursor-default items-center gap-1 overflow-hidden bg-neutral-100 py-0 pr-[0.2rem] pl-[0.4rem] text-sm leading-none text-neutral-950 outline-none focus-within:bg-neutral-950 focus-within:text-white [@media(hover:hover)]:data-highlighted:bg-neutral-950 [@media(hover:hover)]:data-highlighted:text-white dark:bg-neutral-800 dark:text-white dark:focus-within:bg-white dark:focus-within:text-neutral-950 dark:[@media(hover:hover)]:data-highlighted:bg-white dark:[@media(hover:hover)]:data-highlighted:text-neutral-950"
+                    aria-label={user.name}
+                    aria-description="Press Backspace or Delete to remove"
+                  >
+                    {user.name}
+                    <Combobox.ChipRemove
+                      className="flex size-4 items-center justify-center border-0 bg-transparent p-0 text-inherit hover:bg-neutral-200 group-focus-within:hover:bg-neutral-700 dark:hover:bg-neutral-700 dark:group-focus-within:hover:bg-neutral-200"
+                      aria-label={`Remove ${user.name}`}
                     >
-                      {user.name}
-                      <Combobox.ChipRemove
-                        className="flex size-4 items-center justify-center border-0 bg-transparent p-0 text-inherit hover:bg-neutral-200 group-focus-within:hover:bg-neutral-700 dark:hover:bg-neutral-700 dark:group-focus-within:hover:bg-neutral-200"
-                        aria-label={`Remove ${user.name}`}
-                      >
-                        <XIcon />
-                      </Combobox.ChipRemove>
-                    </Combobox.Chip>
-                  ))}
-                  <Combobox.Input
-                    id={id}
-                    placeholder={value.length > 0 ? '' : 'e.g. Michael'}
-                    className="h-[calc(1.5rem-2px)] min-w-12 flex-1 border-0 bg-white p-0 text-sm any-pointer-coarse:text-base dark:bg-neutral-950 font-normal text-neutral-950 outline-none placeholder:text-neutral-500 dark:placeholder:text-neutral-400 dark:text-white"
-                  />
-                </React.Fragment>
-              )}
-            </Combobox.Value>
-          </Combobox.Chips>
+                      <XIcon />
+                    </Combobox.ChipRemove>
+                  </Combobox.Chip>
+                ))}
+                <Combobox.Input
+                  id={id}
+                  placeholder={value.length > 0 ? '' : 'e.g. Michael'}
+                  aria-description={
+                    value.length > 0
+                      ? `${value.length} selected. From the start of the input, press Left Arrow to focus the selected items`
+                      : undefined
+                  }
+                  className="h-[calc(1.5rem-2px)] min-w-12 flex-1 border-0 bg-white p-0 text-sm any-pointer-coarse:text-base dark:bg-neutral-950 font-normal text-neutral-950 outline-none placeholder:text-neutral-500 dark:placeholder:text-neutral-400 dark:text-white"
+                />
+              </Combobox.Chips>
+            )}
+          </Combobox.Value>
         </Combobox.InputGroup>
       </div>
 
@@ -4565,6 +5217,7 @@ export default function ExampleAsyncMultipleCombobox() {
     <Combobox.Root
       items={items}
       itemToStringLabel={(user: DirectoryUser) => user.name}
+      isItemEqualToValue={(item, value) => item.id === value.id}
       multiple
       filter={null}
       onOpenChangeComplete={(open) => {
@@ -4625,30 +5278,41 @@ export default function ExampleAsyncMultipleCombobox() {
           Assign reviewers
         </label>
         <Combobox.InputGroup className={styles.InputGroup}>
-          <Combobox.Chips className={styles.Chips}>
-            <Combobox.Value>
-              {(value: DirectoryUser[]) => (
-                <React.Fragment>
-                  {value.map((user) => (
-                    <Combobox.Chip key={user.id} className={styles.Chip} aria-label={user.name}>
-                      {user.name}
-                      <Combobox.ChipRemove
-                        className={styles.ChipRemove}
-                        aria-label={`Remove ${user.name}`}
-                      >
-                        <XIcon />
-                      </Combobox.ChipRemove>
-                    </Combobox.Chip>
-                  ))}
-                  <Combobox.Input
-                    id={id}
-                    placeholder={value.length > 0 ? '' : 'e.g. Michael'}
-                    className={styles.Input}
-                  />
-                </React.Fragment>
-              )}
-            </Combobox.Value>
-          </Combobox.Chips>
+          <Combobox.Value>
+            {(value: DirectoryUser[]) => (
+              <Combobox.Chips
+                className={styles.Chips}
+                aria-label={value.length > 0 ? 'Selected reviewers' : undefined}
+              >
+                {value.map((user) => (
+                  <Combobox.Chip
+                    key={user.id}
+                    className={styles.Chip}
+                    aria-label={user.name}
+                    aria-description="Press Backspace or Delete to remove"
+                  >
+                    {user.name}
+                    <Combobox.ChipRemove
+                      className={styles.ChipRemove}
+                      aria-label={`Remove ${user.name}`}
+                    >
+                      <XIcon />
+                    </Combobox.ChipRemove>
+                  </Combobox.Chip>
+                ))}
+                <Combobox.Input
+                  id={id}
+                  placeholder={value.length > 0 ? '' : 'e.g. Michael'}
+                  aria-description={
+                    value.length > 0
+                      ? `${value.length} selected. From the start of the input, press Left Arrow to focus the selected items`
+                      : undefined
+                  }
+                  className={styles.Input}
+                />
+              </Combobox.Chips>
+            )}
+          </Combobox.Value>
         </Combobox.InputGroup>
       </div>
 
@@ -4992,36 +5656,43 @@ export default function ExampleCreatableCombobox() {
             Labels
           </label>
           <Combobox.InputGroup className="flex min-h-8 w-64 cursor-text flex-wrap items-center gap-0.5 border border-neutral-950 bg-white dark:bg-neutral-950 px-2 py-1 focus-within:outline-2 focus-within:-outline-offset-1 focus-within:outline-neutral-950 dark:focus-within:outline-white has-[button]:px-1 dark:border-white min-[32rem]:w-[22rem]">
-            <Combobox.Chips className="flex w-full flex-wrap items-center gap-1">
-              <Combobox.Value>
-                {(value: LabelItem[]) => (
-                  <React.Fragment>
-                    {value.map((label) => (
-                      <Combobox.Chip
-                        key={label.id}
-                        className="group flex min-h-[calc(1.5rem-2px)] cursor-default items-center gap-1 overflow-hidden bg-neutral-100 py-0 pr-[0.2rem] pl-[0.4rem] text-sm leading-none text-neutral-950 outline-none focus-within:bg-neutral-950 focus-within:text-white [@media(hover:hover)]:data-highlighted:bg-neutral-950 [@media(hover:hover)]:data-highlighted:text-white dark:bg-neutral-800 dark:text-white dark:focus-within:bg-white dark:focus-within:text-neutral-950 dark:[@media(hover:hover)]:data-highlighted:bg-white dark:[@media(hover:hover)]:data-highlighted:text-neutral-950"
-                        aria-label={label.value}
+            <Combobox.Value>
+              {(value: LabelItem[]) => (
+                <Combobox.Chips
+                  className="flex w-full flex-wrap items-center gap-1"
+                  aria-label={value.length > 0 ? 'Selected labels' : undefined}
+                >
+                  {value.map((label) => (
+                    <Combobox.Chip
+                      key={label.id}
+                      className="group flex min-h-[calc(1.5rem-2px)] cursor-default items-center gap-1 overflow-hidden bg-neutral-100 py-0 pr-[0.2rem] pl-[0.4rem] text-sm leading-none text-neutral-950 outline-none focus-within:bg-neutral-950 focus-within:text-white [@media(hover:hover)]:data-highlighted:bg-neutral-950 [@media(hover:hover)]:data-highlighted:text-white dark:bg-neutral-800 dark:text-white dark:focus-within:bg-white dark:focus-within:text-neutral-950 dark:[@media(hover:hover)]:data-highlighted:bg-white dark:[@media(hover:hover)]:data-highlighted:text-neutral-950"
+                      aria-label={label.value}
+                      aria-description="Press Backspace or Delete to remove"
+                    >
+                      {label.value}
+                      <Combobox.ChipRemove
+                        className="flex size-4 items-center justify-center border-0 bg-transparent p-0 text-inherit hover:bg-neutral-200 group-focus-within:hover:bg-neutral-700 dark:hover:bg-neutral-700 dark:group-focus-within:hover:bg-neutral-200"
+                        aria-label={`Remove ${label.value}`}
                       >
-                        {label.value}
-                        <Combobox.ChipRemove
-                          className="flex size-4 items-center justify-center border-0 bg-transparent p-0 text-inherit hover:bg-neutral-200 group-focus-within:hover:bg-neutral-700 dark:hover:bg-neutral-700 dark:group-focus-within:hover:bg-neutral-200"
-                          aria-label={`Remove ${label.value}`}
-                        >
-                          <XIcon />
-                        </Combobox.ChipRemove>
-                      </Combobox.Chip>
-                    ))}
-                    <Combobox.Input
-                      ref={comboboxInputRef}
-                      id={id}
-                      placeholder={value.length > 0 ? '' : 'e.g. bug'}
-                      className="h-[calc(1.5rem-2px)] min-w-12 flex-1 border-0 bg-white p-0 text-sm any-pointer-coarse:text-base dark:bg-neutral-950 font-normal text-neutral-950 outline-none placeholder:text-neutral-500 dark:placeholder:text-neutral-400 dark:text-white"
-                      onKeyDown={handleInputKeyDown}
-                    />
-                  </React.Fragment>
-                )}
-              </Combobox.Value>
-            </Combobox.Chips>
+                        <XIcon />
+                      </Combobox.ChipRemove>
+                    </Combobox.Chip>
+                  ))}
+                  <Combobox.Input
+                    ref={comboboxInputRef}
+                    id={id}
+                    placeholder={value.length > 0 ? '' : 'e.g. bug'}
+                    aria-description={
+                      value.length > 0
+                        ? `${value.length} selected. From the start of the input, press Left Arrow to focus the selected items`
+                        : undefined
+                    }
+                    className="h-[calc(1.5rem-2px)] min-w-12 flex-1 border-0 bg-white p-0 text-sm any-pointer-coarse:text-base dark:bg-neutral-950 font-normal text-neutral-950 outline-none placeholder:text-neutral-500 dark:placeholder:text-neutral-400 dark:text-white"
+                    onKeyDown={handleInputKeyDown}
+                  />
+                </Combobox.Chips>
+              )}
+            </Combobox.Value>
           </Combobox.InputGroup>
         </div>
 
@@ -5804,36 +6475,43 @@ export default function ExampleCreatableCombobox() {
             Labels
           </label>
           <Combobox.InputGroup className={styles.InputGroup}>
-            <Combobox.Chips className={styles.Chips}>
-              <Combobox.Value>
-                {(value: LabelItem[]) => (
-                  <React.Fragment>
-                    {value.map((label) => (
-                      <Combobox.Chip
-                        key={label.id}
-                        className={styles.Chip}
-                        aria-label={label.value}
+            <Combobox.Value>
+              {(value: LabelItem[]) => (
+                <Combobox.Chips
+                  className={styles.Chips}
+                  aria-label={value.length > 0 ? 'Selected labels' : undefined}
+                >
+                  {value.map((label) => (
+                    <Combobox.Chip
+                      key={label.id}
+                      className={styles.Chip}
+                      aria-label={label.value}
+                      aria-description="Press Backspace or Delete to remove"
+                    >
+                      {label.value}
+                      <Combobox.ChipRemove
+                        className={styles.ChipRemove}
+                        aria-label={`Remove ${label.value}`}
                       >
-                        {label.value}
-                        <Combobox.ChipRemove
-                          className={styles.ChipRemove}
-                          aria-label={`Remove ${label.value}`}
-                        >
-                          <XIcon />
-                        </Combobox.ChipRemove>
-                      </Combobox.Chip>
-                    ))}
-                    <Combobox.Input
-                      ref={comboboxInputRef}
-                      id={id}
-                      placeholder={value.length > 0 ? '' : 'e.g. bug'}
-                      className={styles.Input}
-                      onKeyDown={handleInputKeyDown}
-                    />
-                  </React.Fragment>
-                )}
-              </Combobox.Value>
-            </Combobox.Chips>
+                        <XIcon />
+                      </Combobox.ChipRemove>
+                    </Combobox.Chip>
+                  ))}
+                  <Combobox.Input
+                    ref={comboboxInputRef}
+                    id={id}
+                    placeholder={value.length > 0 ? '' : 'e.g. bug'}
+                    aria-description={
+                      value.length > 0
+                        ? `${value.length} selected. From the start of the input, press Left Arrow to focus the selected items`
+                        : undefined
+                    }
+                    className={styles.Input}
+                    onKeyDown={handleInputKeyDown}
+                  />
+                </Combobox.Chips>
+              )}
+            </Combobox.Value>
           </Combobox.InputGroup>
         </div>
 
@@ -6486,6 +7164,28 @@ const virtualizedItems: VirtualizedItem[] = Array.from({ length: 10000 }, (_, in
 type Virtualizer = ReturnType<typeof useVirtualizer<HTMLDivElement, Element>>;
 ```
 
+#### Memoizing items
+
+Memoizing each item is a simpler alternative to virtualization for datasets up to roughly 1,000 items. Wrap each item in [`React.memo`](https://react.dev/reference/react/memo) and pass the item as a prop so unchanged items skip re-rendering. While memoization speeds up typing, it does not speed up opening; with a large enough number of items, the mount cost dominates, and virtualization becomes necessary to keep the open interaction fast on low-end devices.
+
+```tsx title="Memoizing list items"
+interface Fruit {
+  id: string;
+  label: string;
+}
+
+const FruitItem = React.memo(function FruitItem({ item }: { item: Fruit }) {
+  return (
+    <Combobox.Item value={item}>
+      <Combobox.ItemIndicator />
+      <span>{item.label}</span>
+    </Combobox.Item>
+  );
+});
+
+<Combobox.List>{(item: Fruit) => <FruitItem key={item.id} item={item} />}</Combobox.List>;
+```
+
 ## API reference
 
 ### Root
@@ -6495,46 +7195,46 @@ Doesn't render its own HTML element.
 
 **Root Props:**
 
-| Prop                 | Type                                                                                                    | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| :------------------- | :------------------------------------------------------------------------------------------------------ | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| name                 | `string`                                                                                                | -       | Identifies the field when a form is submitted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| defaultValue         | `Value[] \| Value \| null`                                                                              | -       | The uncontrolled selected value of the combobox when it's initially rendered. To render a controlled combobox, use the `value` prop instead.                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| value                | `Value[] \| Value \| null`                                                                              | -       | The selected value of the combobox. Use when controlled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| onValueChange        | `((value: Value[] \| Value \| null, eventDetails: Combobox.Root.ChangeEventDetails) => void)`           | -       | Event handler called when the selected value of the combobox changes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| defaultInputValue    | `string \| number \| string[]`                                                                          | -       | The uncontrolled input value when initially rendered. To render a controlled input, use the `inputValue` prop instead.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| inputValue           | `string \| string[] \| number`                                                                          | -       | The input value of the combobox. Use when controlled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| onInputValueChange   | `((inputValue: string, eventDetails: Combobox.Root.ChangeEventDetails) => void)`                        | -       | Event handler called when the input value changes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| defaultOpen          | `boolean`                                                                                               | `false` | Whether the popup is initially open. To render a controlled popup, use the `open` prop instead.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| open                 | `boolean`                                                                                               | -       | Whether the popup is currently open. Use when controlled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| onOpenChange         | `((open: boolean, eventDetails: Combobox.Root.ChangeEventDetails) => void)`                             | -       | Event handler called when the popup is opened or closed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| autoHighlight        | `boolean`                                                                                               | `false` | Whether the first matching item is highlighted automatically while filtering.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| highlightItemOnHover | `boolean`                                                                                               | `true`  | Whether moving the pointer over items should highlight them.&#xA;Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.                                                                                                                                                                                                                                                                                                                                                                                           |
-| actionsRef           | `React.RefObject<Combobox.Root.Actions \| null>`                                                        | -       | A ref to imperative actions. `unmount`: Manually unmounts the combobox.&#xA;Call this after any externally controlled closing animation finishes.                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| autoComplete         | `string`                                                                                                | -       | Provides a hint to the browser for autofill.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| filter               | `((itemValue: Value, query: string, itemToString?: ((itemValue: Value) => string)) => boolean) \| null` | -       | ComboboxFilter function used to match items vs input query.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| filteredItems        | `any[] \| Group[]`                                                                                      | -       | Filtered items to display in the list.&#xA;When provided, the list will use these items instead of filtering the `items` prop internally.&#xA;Use when you want to control filtering logic externally with the `useFilter()` hook.                                                                                                                                                                                                                                                                                                                                    |
-| form                 | `string`                                                                                                | -       | Identifies the form that owns the internal input.&#xA;Useful when the combobox is rendered outside the form.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| grid                 | `boolean`                                                                                               | `false` | Whether list items are presented in a grid layout.&#xA;When enabled, arrow keys navigate across rows and columns inferred from DOM rows.                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| inline               | `boolean`                                                                                               | `false` | Whether the list is rendered inline without using the component's own popup. Specify `open` unconditionally in conjunction with this prop so the list is considered&#xA;visible: `<Combobox.Root inline open>` In a `Combobox.Root` > `Dialog.Root` composition, bind the Combobox's `open` and&#xA;`onOpenChange` props to the `Dialog`'s `open` and `onOpenChange` state instead so the&#xA;component resets its transient state (filter query, highlighted item, and input value) when&#xA;the dialog closes.                                                      |
-| isItemEqualToValue   | `((itemValue: Value, value: Value) => boolean)`                                                         | -       | Custom comparison logic used to determine if a combobox item value matches the current selected value. Useful when item values are objects without matching referentially.&#xA;Defaults to `Object.is` comparison.                                                                                                                                                                                                                                                                                                                                                    |
-| itemToStringLabel    | `((itemValue: Value) => string)`                                                                        | -       | When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for display in the input.&#xA;If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop.                                                                                                                                                                                                                                                                    |
-| itemToStringValue    | `((itemValue: Value) => string)`                                                                        | -       | When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for form submission.&#xA;If the shape of the object is `{ value, label }`, the value will be used automatically without needing to specify this prop.                                                                                                                                                                                                                                                                         |
-| items                | `any[] \| Group[]`                                                                                      | -       | The items to be displayed in the list.&#xA;Can be either a flat array of items or an array of groups with items.                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| limit                | `number`                                                                                                | `-1`    | The maximum number of items to display in the list.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| locale               | `Intl.LocalesArgument`                                                                                  | -       | The locale to use for string comparison.&#xA;Defaults to the user's runtime locale.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| loopFocus            | `boolean`                                                                                               | `true`  | Whether to loop keyboard focus back to the input when the end of the list is reached while using the arrow keys. The first item can then be reached by pressing ArrowDown again from the input, or the last item can be reached by pressing ArrowUp from the input.&#xA;The input is always included in the focus loop per [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).&#xA;When disabled, focus does not move when on the last element and the user presses ArrowDown, or when on the first element and the user presses ArrowUp. |
-| modal                | `boolean`                                                                                               | `false` | Determines if the popup enters a modal state when open. `true`: user interaction is limited to the popup: document page scroll is locked and pointer interactions on outside elements are disabled.`false`: user interaction with the rest of the document is allowed.                                                                                                                                                                                                                                                                                                |
-| multiple             | `boolean`                                                                                               | `false` | Whether multiple items can be selected.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| onItemHighlighted    | `((highlightedValue: Value \| undefined, eventDetails: Combobox.Root.HighlightEventDetails) => void)`   | -       | Callback fired when an item is highlighted or unhighlighted.&#xA;Receives the highlighted item value (or `undefined` if no item is highlighted) and event details with a `reason` property describing why the highlight changed.&#xA;The `reason` can be: `'keyboard'`: the highlight changed due to keyboard navigation.`'pointer'`: the highlight changed due to pointer hovering.`'none'`: the highlight changed programmatically.                                                                                                                                 |
-| onOpenChangeComplete | `((open: boolean) => void)`                                                                             | -       | Event handler called after any animations complete when the popup is opened or closed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| openOnInputClick     | `boolean`                                                                                               | `true`  | Whether the popup opens when clicking the input.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| virtualized          | `boolean`                                                                                               | `false` | Whether the items are being externally virtualized.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| disabled             | `boolean`                                                                                               | `false` | Whether the component should ignore user interaction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| readOnly             | `boolean`                                                                                               | `false` | Whether the user should be unable to choose a different option from the popup.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| required             | `boolean`                                                                                               | `false` | Whether the user must choose a value before submitting a form.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| inputRef             | `React.Ref<HTMLInputElement>`                                                                           | -       | A ref to the hidden input element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| id                   | `string`                                                                                                | -       | The id of the component.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| children             | `React.ReactNode`                                                                                       | -       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Prop                 | Type                                                                                                  | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| :------------------- | :---------------------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| name                 | `string`                                                                                              | -       | Identifies the field when a form is submitted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| defaultValue         | `Value[] \| Value \| null`                                                                            | -       | The uncontrolled selected value of the combobox when it's initially rendered. To render a controlled combobox, use the `value` prop instead.                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| value                | `Value[] \| Value \| null`                                                                            | -       | The selected value of the combobox. Use when controlled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| onValueChange        | `((value: Value[] \| Value \| null, eventDetails: Combobox.Root.ChangeEventDetails) => void)`         | -       | Event handler called when the selected value of the combobox changes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| defaultInputValue    | `string \| number \| string[]`                                                                        | -       | The uncontrolled input value when initially rendered. To render a controlled input, use the `inputValue` prop instead.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| inputValue           | `string \| string[] \| number`                                                                        | -       | The input value of the combobox. Use when controlled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| onInputValueChange   | `((inputValue: string, eventDetails: Combobox.Root.ChangeEventDetails) => void)`                      | -       | Event handler called when the input value changes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| defaultOpen          | `boolean`                                                                                             | `false` | Whether the popup is initially open. To render a controlled popup, use the `open` prop instead.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| open                 | `boolean`                                                                                             | -       | Whether the popup is currently open. Use when controlled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| onOpenChange         | `((open: boolean, eventDetails: Combobox.Root.ChangeEventDetails) => void)`                           | -       | Event handler called when the popup is opened or closed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| autoHighlight        | `boolean`                                                                                             | `false` | Whether the first matching item is highlighted automatically while filtering.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| highlightItemOnHover | `boolean`                                                                                             | `true`  | Whether moving the pointer over items should highlight them.&#xA;Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.                                                                                                                                                                                                                                                                                                                                                                                           |
+| actionsRef           | `React.RefObject<Combobox.Root.Actions \| null>`                                                      | -       | A ref to imperative actions. `unmount`: Manually unmounts the combobox.&#xA;Call this after any externally controlled closing animation finishes.                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| autoComplete         | `string`                                                                                              | -       | Provides a hint to the browser for autofill.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| filter               | `((item: Item, query: string, itemToString?: ((item: Item) => string)) => boolean) \| null`           | -       | ComboboxFilter function used to match items vs input query.&#xA;Receives the source item, which is the derived value's item when `items` is a `createItems()`&#xA;collection, and the item itself otherwise.                                                                                                                                                                                                                                                                                                                                                          |
+| filteredItems        | `Item[] \| Group<Item>[]`                                                                             | -       | Filtered items to display in the list.&#xA;When provided, the list uses these items instead of filtering the `items` prop internally.&#xA;When `items` is also provided, this array must preserve its flat or grouped structure.&#xA;With a `createItems()` collection, pass source items rather than derived values.&#xA;Nullish entries are not supported, as in `items`.&#xA;Use when you want to control filtering logic externally with the `useFilter()` hook.                                                                                                  |
+| form                 | `string`                                                                                              | -       | Identifies the form that owns the internal input.&#xA;Useful when the combobox is rendered outside the form.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| grid                 | `boolean`                                                                                             | `false` | Whether list items are presented in a grid layout.&#xA;When enabled, arrow keys navigate across rows and columns inferred from DOM rows.                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| inline               | `boolean`                                                                                             | `false` | Whether the list is rendered inline without using the component's own popup. Specify `open` unconditionally in conjunction with this prop so the list is considered&#xA;visible: `<Combobox.Root inline open>` In a `Combobox.Root` > `Dialog.Root` composition, bind the Combobox's `open` and&#xA;`onOpenChange` props to the `Dialog`'s `open` and `onOpenChange` state instead so the&#xA;component resets its transient state (filter query, highlighted item, and input value) when&#xA;the dialog closes.                                                      |
+| isItemEqualToValue   | `((itemValue: Value, value: Value) => boolean)`                                                       | -       | Custom comparison logic used to determine if a combobox item value matches the current selected value. Useful when item values are objects without matching referentially.&#xA;With a `createItems()` collection, both arguments are derived values.&#xA;Defaults to `Object.is` comparison.                                                                                                                                                                                                                                                                          |
+| itemToStringLabel    | `((itemValue: Value) => string)`                                                                      | -       | When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for display in the input.&#xA;If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop.&#xA;With a `createItems()` collection, this receives the derived value, and the collection's&#xA;`getLabel` takes precedence for values it can resolve.                                                                                                            |
+| itemToStringValue    | `((itemValue: Value) => string)`                                                                      | -       | When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for form submission.&#xA;If the shape of the object is `{ value, label }`, the value will be used automatically without needing to specify this prop.&#xA;With a `createItems()` collection, this receives the derived value.                                                                                                                                                                                                 |
+| items                | `any[] \| Group[] \| ComboboxItemCollection<Item, Value>`                                             | -       | The items to be displayed in the list.&#xA;Can be a flat array of items, an array of groups with items, or a collection created by&#xA;the `createItems()` function, which derives each item's selection value and label.&#xA;Nullish entries are not supported: remove them from the data before passing it.                                                                                                                                                                                                                                                         |
+| limit                | `number`                                                                                              | `-1`    | The maximum number of items to display in the list.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| locale               | `Intl.LocalesArgument`                                                                                | -       | The locale to use for string comparison.&#xA;Defaults to the user's runtime locale.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| loopFocus            | `boolean`                                                                                             | `true`  | Whether to loop keyboard focus back to the input when the end of the list is reached while using the arrow keys. The first item can then be reached by pressing ArrowDown again from the input, or the last item can be reached by pressing ArrowUp from the input.&#xA;The input is always included in the focus loop per [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).&#xA;When disabled, focus does not move when on the last element and the user presses ArrowDown, or when on the first element and the user presses ArrowUp. |
+| modal                | `boolean`                                                                                             | `false` | Determines if the popup enters a modal state when open. `true`: user interaction is limited to the popup: document page scroll is locked and pointer interactions on outside elements are disabled.`false`: user interaction with the rest of the document is allowed. On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior.                                                                                                                       |
+| multiple             | `boolean`                                                                                             | `false` | Whether multiple items can be selected.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| onItemHighlighted    | `((highlightedValue: Value \| undefined, eventDetails: Combobox.Root.HighlightEventDetails) => void)` | -       | Callback fired when an item is highlighted or unhighlighted.&#xA;Receives the highlighted item value (or `undefined` if no item is highlighted) and event details with a `reason` property describing why the highlight changed.&#xA;The `reason` can be: `'keyboard'`: the highlight changed due to keyboard navigation.`'pointer'`: the highlight changed due to pointer hovering.`'none'`: the highlight changed programmatically.                                                                                                                                 |
+| onOpenChangeComplete | `((open: boolean) => void)`                                                                           | -       | Event handler called after any animations complete when the popup is opened or closed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| openOnInputClick     | `boolean`                                                                                             | `true`  | Whether the popup opens when clicking the input.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| virtualized          | `boolean`                                                                                             | `false` | Whether the items are being externally virtualized.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| disabled             | `boolean`                                                                                             | `false` | Whether the component should ignore user interaction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| readOnly             | `boolean`                                                                                             | `false` | Whether the user should be unable to choose a different option from the popup.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| required             | `boolean`                                                                                             | `false` | Whether the user must choose a value before submitting a form.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| inputRef             | `React.Ref<HTMLInputElement>`                                                                         | -       | A ref to the hidden input element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| id                   | `string`                                                                                              | -       | The id of the component.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| children             | `React.ReactNode`                                                                                     | -       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 
 **`autoComplete` Prop References:**
 
@@ -6561,6 +7261,7 @@ type ComboboxRootActions = { unmount: () => void };
 ```typescript
 type ComboboxRootChangeEventReason =
   | 'trigger-press'
+  | 'input-press'
   | 'outside-press'
   | 'item-press'
   | 'close-press'
@@ -6571,6 +7272,7 @@ type ComboboxRootChangeEventReason =
   | 'input-clear'
   | 'clear-press'
   | 'chip-remove-press'
+  | 'cancel-open'
   | 'none';
 ```
 
@@ -6578,8 +7280,8 @@ type ComboboxRootChangeEventReason =
 
 ```typescript
 type ComboboxRootChangeEventDetails = (
-  | { reason: 'none'; event: Event }
   | { reason: 'trigger-press'; event: MouseEvent | PointerEvent | TouchEvent | KeyboardEvent }
+  | { reason: 'input-press'; event: MouseEvent | PointerEvent | TouchEvent | KeyboardEvent }
   | { reason: 'outside-press'; event: MouseEvent | PointerEvent | TouchEvent }
   | { reason: 'item-press'; event: MouseEvent | PointerEvent | KeyboardEvent }
   | { reason: 'close-press'; event: MouseEvent | PointerEvent | KeyboardEvent }
@@ -6590,6 +7292,8 @@ type ComboboxRootChangeEventDetails = (
   | { reason: 'input-clear'; event: Event | FocusEvent | InputEvent }
   | { reason: 'clear-press'; event: MouseEvent | PointerEvent | KeyboardEvent }
   | { reason: 'chip-remove-press'; event: MouseEvent | PointerEvent | KeyboardEvent }
+  | { reason: 'cancel-open'; event: MouseEvent }
+  | { reason: 'none'; event: Event }
 ) & {
   /** Cancels Base UI from handling the event. */
   cancel: () => void;
@@ -6601,6 +7305,11 @@ type ComboboxRootChangeEventDetails = (
   isPropagationAllowed: boolean;
   /** The element that triggered the event, if applicable. */
   trigger: Element | undefined;
+  /**
+   * When `reason` is `input-clear` in multiple mode, indicates whether an item press caused the
+   * clear. Automatic cleanup clears omit this property.
+   */
+  isItemPress?: boolean;
 };
 ```
 
@@ -6665,6 +7374,8 @@ type ComboboxTriggerState = {
   open: boolean;
   /** Whether the component should ignore user interaction. */
   disabled: boolean;
+  /** Whether the component should ignore user edits. */
+  readOnly: boolean;
   /** Indicates which side the corresponding popup is positioned relative to its anchor. */
   popupSide: Side | null;
   /** Present when the corresponding items list is empty. */
@@ -6691,10 +7402,10 @@ Doesn't render its own HTML element.
 
 **Value Props:**
 
-| Prop        | Type                                                           | Default | Description                                                                                                                                          |
-| :---------- | :------------------------------------------------------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
-| placeholder | `React.ReactNode`                                              | -       | The placeholder value to display when no value is selected.&#xA;This is overridden by `children` if specified, or by a null item's label in `items`. |
-| children    | `React.ReactNode \| ((selectedValue: any) => React.ReactNode)` | -       | -                                                                                                                                                    |
+| Prop        | Type                                                           | Default | Description                                                                                                                                                                                    |
+| :---------- | :------------------------------------------------------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| placeholder | `React.ReactNode`                                              | -       | The placeholder value to display when no value is selected.&#xA;This is overridden by `children` if specified, or by a null item's label in `items`.                                           |
+| children    | `React.ReactNode \| ((selectedValue: any) => React.ReactNode)` | -       | Accepts a function that returns a `ReactNode` to format the selected value.&#xA;Treat the value as read-only: in `multiple` mode it may be a shared frozen array&#xA;when nothing is selected. |
 
 ### Value.Props
 
@@ -6815,7 +7526,7 @@ Renders a `<button>` element.
 | data-popup-open     | -    | Present when the corresponding popup is open. |
 | data-disabled       | -    | Present when the button is disabled.          |
 | data-visible        | -    | Present when the clear button is visible.     |
-| data-starting-style | -    | Present when the button is animating in.      |
+| data-starting-style | -    | Present when the button begins animating in.  |
 | data-ending-style   | -    | Present when the button is animating out.     |
 
 ### Clear.Props
@@ -6905,12 +7616,12 @@ Renders a `<div>` element.
 
 **Backdrop Data Attributes:**
 
-| Attribute           | Type | Description                              |
-| :------------------ | :--- | :--------------------------------------- |
-| data-open           | -    | Present when the popup is open.          |
-| data-closed         | -    | Present when the popup is closed.        |
-| data-starting-style | -    | Present when the popup is animating in.  |
-| data-ending-style   | -    | Present when the popup is animating out. |
+| Attribute           | Type | Description                                 |
+| :------------------ | :--- | :------------------------------------------ |
+| data-open           | -    | Present when the popup is open.             |
+| data-closed         | -    | Present when the popup is closed.           |
+| data-starting-style | -    | Present when the popup begins animating in. |
+| data-ending-style   | -    | Present when the popup is animating out.    |
 
 ### Backdrop.Props
 
@@ -7047,11 +7758,11 @@ Renders a `<div>` element.
 | :------------------ | :------------------------------------------------------------------------- | :-------------------------------------------------------------------- |
 | data-open           | -                                                                          | Present when the popup is open.                                       |
 | data-closed         | -                                                                          | Present when the popup is closed.                                     |
+| data-anchor-hidden  | -                                                                          | Present when the anchor is hidden.                                    |
 | data-align          | `'start' \| 'center' \| 'end'`                                             | Indicates how the popup is aligned relative to specified side.        |
 | data-empty          | -                                                                          | Present when the items list is empty.                                 |
-| data-instant        | `'click' \| 'dismiss'`                                                     | Present if animations should be instant.                              |
 | data-side           | `'top' \| 'bottom' \| 'left' \| 'right' \| 'inline-end' \| 'inline-start'` | Indicates which side the popup is positioned relative to the trigger. |
-| data-starting-style | -                                                                          | Present when the popup is animating in.                               |
+| data-starting-style | -                                                                          | Present when the popup begins animating in.                           |
 | data-ending-style   | -                                                                          | Present when the popup is animating out.                              |
 
 ### Popup.Props
@@ -7230,17 +7941,17 @@ type ComboboxGroupLabelState = {};
 
 ### Separator
 
-A separator element accessible to screen readers.
+A visual separator between items or groups.
 Renders a `<div>` element.
 
 **Separator Props:**
 
-| Prop        | Type                                                                                   | Default        | Description                                                                                                                                                                                   |
-| :---------- | :------------------------------------------------------------------------------------- | :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| orientation | `Orientation`                                                                          | `'horizontal'` | The orientation of the separator.                                                                                                                                                             |
-| className   | `string \| ((state: SeparatorState) => string \| undefined)`                           | -              | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                      |
-| style       | `React.CSSProperties \| ((state: SeparatorState) => React.CSSProperties \| undefined)` | -              | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                   |
-| render      | `ReactElement \| ((props: HTMLProps, state: SeparatorState) => ReactElement)`          | -              | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
+| Prop        | Type                                                                                             | Default        | Description                                                                                                                                                                                   |
+| :---------- | :----------------------------------------------------------------------------------------------- | :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| orientation | `Orientation`                                                                                    | `'horizontal'` | The orientation of the separator.                                                                                                                                                             |
+| className   | `string \| ((state: Combobox.Separator.State) => string \| undefined)`                           | -              | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                      |
+| style       | `React.CSSProperties \| ((state: Combobox.Separator.State) => React.CSSProperties \| undefined)` | -              | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                   |
+| render      | `ReactElement \| ((props: HTMLProps, state: Combobox.Separator.State) => ReactElement)`          | -              | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
 
 ### Separator.Props
 
@@ -7488,10 +8199,10 @@ Renders a `<span>` element.
 
 **ItemIndicator Data Attributes:**
 
-| Attribute           | Type | Description                                  |
-| :------------------ | :--- | :------------------------------------------- |
-| data-starting-style | -    | Present when the indicator is animating in.  |
-| data-ending-style   | -    | Present when the indicator is animating out. |
+| Attribute           | Type | Description                                     |
+| :------------------ | :--- | :---------------------------------------------- |
+| data-starting-style | -    | Present when the indicator begins animating in. |
+| data-ending-style   | -    | Present when the indicator is animating out.    |
 
 ### ItemIndicator.Props
 
@@ -7508,6 +8219,46 @@ type ComboboxItemIndicatorState = {
 };
 ```
 
+### ComboboxItemCollection
+
+An opaque collection created by `createItems()`.
+
+It carries the source item and derived value types so the root can infer the list item and
+selection value types.
+
+Pass it directly to the root's `items` prop; it has no public members.
+
+### createItems
+
+Creates a collection for the root's `items` prop. Values and labels are derived on first use.
+
+Accepts either a flat item array or an array of groups. The `getValue` and `getLabel` accessors
+receive items, not groups.
+
+Items cannot have an `items` array property because they would be interpreted as groups.
+Rename that field or cast the data when the runtime values are known not to contain arrays.
+
+The data must not contain nullish entries: remove them before creating the collection, as for
+the root's `items` prop.
+
+Create static collections at module scope. Wrap dynamic collections in `React.useMemo()` keyed
+by their data.
+
+**Parameters:**
+
+| Parameter | Type                                                       | Default | Description                                                                 |
+| :-------- | :--------------------------------------------------------- | :------ | :-------------------------------------------------------------------------- |
+| data      | `ComboboxItemsData<Item> \| undefined`                     | -       | The flat or grouped source items, or `undefined` while they are loading.    |
+| options   | `CreateComboboxItemsOptions<Item, ComboboxPrimitiveValue>` | -       | Functions that derive each source item's selection value and display label. |
+
+**Return Value:**
+
+A collection whose selection value is the `getValue` accessor's return value.
+
+```tsx
+type ReturnValue = ComboboxItemCollection<Item, ComboboxPrimitiveValue>;
+```
+
 ### InputGroup
 
 A wrapper for the input and its associated controls.
@@ -7580,7 +8331,7 @@ Matches items against a query using `Intl.Collator` for robust string matching.
 
 | Parameter | Type                    | Default | Description |
 | :-------- | :---------------------- | :------ | :---------- |
-| options?  | `ComboboxFilterOptions` | -       | -           |
+| options?  | `ComboboxFilterOptions` | `{}`    | -           |
 
 **Return Value:**
 
@@ -7591,6 +8342,7 @@ type ReturnValue = ComboboxFilter;
 ### useFilteredItems
 
 Returns the internally filtered items.
+Treat the result as read-only: it is internal state and may be a shared frozen array.
 
 **Return Value:**
 
@@ -7622,7 +8374,10 @@ type ComboboxFilterOptions = {
    * @default false
    */
   multiple?: boolean;
-  /** The current value of the combobox. */
+  /**
+   * The current value of the combobox, used to keep every item visible while the query still
+   * matches the selection.
+   */
   value?: any;
   /**
    * The locale to use for string comparison.
@@ -7632,6 +8387,36 @@ type ComboboxFilterOptions = {
 };
 ```
 
+### ComboboxPrimitiveValue
+
+```typescript
+type ComboboxPrimitiveValue = string | number | bigint | boolean;
+```
+
+### CreateComboboxItemsOptions
+
+```typescript
+type CreateComboboxItemsOptions<
+  Item,
+  Value extends ComboboxPrimitiveValue = ComboboxPrimitiveValue,
+> = {
+  /**
+   * Projects an item to the primitive value that identifies it, used as the item's
+   * selection value.
+   *
+   * `null` and `undefined` are reserved for no selection, and each item must derive a unique
+   * value. Prefer stable IDs from your application data.
+   */
+  getValue: (item: Item) => Value;
+  /**
+   * Projects an item to the label string that represents it in the input and when matching the
+   * typed query. The root's `itemToStringLabel` prop is the fallback for values whose item is in
+   * neither the data nor the current `filteredItems`.
+   */
+  getLabel: (item: Item) => string;
+};
+```
+
 ## External Types
 
 ### Side
@@ -7699,7 +8484,8 @@ type Orientation = 'horizontal' | 'vertical';
 - `Combobox.Separator`: `Combobox.Separator`, `Combobox.Separator.Props`, `Combobox.Separator.State`
 - `Combobox.useFilter`
 - `Combobox.useFilteredItems`
-- `Default`: `ComboboxFilter`, `ComboboxFilterOptions`, `ComboboxRootProps`, `ComboboxRootState`, `ComboboxRootActions`, `ComboboxRootChangeEventReason`, `ComboboxRootChangeEventDetails`, `ComboboxRootHighlightEventReason`, `ComboboxRootHighlightEventDetails`, `ComboboxLabelState`, `ComboboxLabelProps`, `ComboboxTriggerState`, `ComboboxTriggerProps`, `ComboboxInputState`, `ComboboxInputProps`, `ComboboxInputGroupState`, `ComboboxInputGroupProps`, `ComboboxPopupState`, `ComboboxPopupProps`, `ComboboxPositionerState`, `ComboboxPositionerProps`, `ComboboxListState`, `ComboboxListProps`, `ComboboxItemState`, `ComboboxItemProps`, `ComboboxItemIndicatorProps`, `ComboboxItemIndicatorState`, `ComboboxValueState`, `ComboboxValueProps`, `ComboboxIconState`, `ComboboxIconProps`, `ComboboxArrowState`, `ComboboxArrowProps`, `ComboboxBackdropProps`, `ComboboxBackdropState`, `ComboboxPortalState`, `ComboboxPortalProps`, `ComboboxEmptyState`, `ComboboxEmptyProps`, `ComboboxGroupState`, `ComboboxGroupProps`, `ComboboxGroupLabelState`, `ComboboxGroupLabelProps`, `ComboboxRowState`, `ComboboxRowProps`, `ComboboxChipsState`, `ComboboxChipsProps`, `ComboboxChipState`, `ComboboxChipProps`, `ComboboxChipRemoveState`, `ComboboxChipRemoveProps`, `ComboboxClearState`, `ComboboxClearProps`, `ComboboxStatusState`, `ComboboxStatusProps`, `ComboboxCollectionState`, `ComboboxCollectionProps`
+- `Combobox.createItems`
+- `Default`: `ComboboxFilter`, `ComboboxFilterOptions`, `ComboboxPrimitiveValue`, `CreateComboboxItemsOptions`, `ComboboxItemCollection`, `ComboboxRootProps`, `ComboboxRootState`, `ComboboxRootActions`, `ComboboxRootChangeEventReason`, `ComboboxRootChangeEventDetails`, `ComboboxRootHighlightEventReason`, `ComboboxRootHighlightEventDetails`, `ComboboxLabelState`, `ComboboxLabelProps`, `ComboboxTriggerState`, `ComboboxTriggerProps`, `ComboboxInputState`, `ComboboxInputProps`, `ComboboxInputGroupState`, `ComboboxInputGroupProps`, `ComboboxPopupState`, `ComboboxPopupProps`, `ComboboxPositionerState`, `ComboboxPositionerProps`, `ComboboxListState`, `ComboboxListProps`, `ComboboxItemState`, `ComboboxItemProps`, `ComboboxItemIndicatorProps`, `ComboboxItemIndicatorState`, `ComboboxValueState`, `ComboboxValueProps`, `ComboboxIconState`, `ComboboxIconProps`, `ComboboxArrowState`, `ComboboxArrowProps`, `ComboboxBackdropProps`, `ComboboxBackdropState`, `ComboboxPortalState`, `ComboboxPortalProps`, `ComboboxEmptyState`, `ComboboxEmptyProps`, `ComboboxGroupState`, `ComboboxGroupProps`, `ComboboxGroupLabelState`, `ComboboxGroupLabelProps`, `ComboboxRowState`, `ComboboxRowProps`, `ComboboxChipsState`, `ComboboxChipsProps`, `ComboboxChipState`, `ComboboxChipProps`, `ComboboxChipRemoveState`, `ComboboxChipRemoveProps`, `ComboboxClearState`, `ComboboxClearProps`, `ComboboxStatusState`, `ComboboxStatusProps`, `ComboboxCollectionState`, `ComboboxCollectionProps`, `ComboboxSeparatorProps`, `ComboboxSeparatorState`
 
 ## Canonical Types
 
@@ -7760,6 +8546,8 @@ Maps `Canonical`: `Alias` — Use Canonical when its namespace is already import
 - `Combobox.Empty.Props`: `ComboboxEmptyProps`
 - `Combobox.Clear.State`: `ComboboxClearState`
 - `Combobox.Clear.Props`: `ComboboxClearProps`
+- `Combobox.Separator.Props`: `ComboboxSeparatorProps`
+- `Combobox.Separator.State`: `ComboboxSeparatorState`
 
 ## useFilter
 
@@ -7770,3 +8558,7 @@ Pass the result to the `filter` prop of `<Combobox.Root>`.
 ## useFilteredItems
 
 Returns the internally filtered items when called inside `<Combobox.Root>`.
+
+## createItems
+
+Normalizes items into a collection for the `items` prop of `<Combobox.Root>`, deriving each item's selection value and label before rendering.