[combobox][select] Add placeholder prop to Value part

docs/reference/generated/combobox-trigger.json

@@ -69,6 +69,9 @@
     },
     "data-focused": {
       "description": "Present when the trigger is focused (when wrapped in Field.Root)."
+    },
+    "data-placeholder": {
+      "description": "Present when the combobox doesn't have a value."
     }
   },
   "cssVariables": {}

docs/reference/generated/combobox-value.json

@@ -2,6 +2,11 @@
   "name": "ComboboxValue",
   "description": "The current value of the combobox.\nDoesn't render its own HTML element.",
   "props": {
+    "placeholder": {
+      "type": "ReactNode",
+      "description": "The placeholder value to display when no value is selected.\nThis is overridden by `children` if specified, or by a null item's label in `items`.",
+      "detailedType": "React.ReactNode"
+    },
     "children": {
       "type": "ReactNode | ((selectedValue: any) => ReactNode)",
       "detailedType": "| React.ReactNode\n| ((selectedValue: any) => ReactNode)"

docs/reference/generated/select-value.json

@@ -2,6 +2,11 @@
   "name": "SelectValue",
   "description": "A text label of the currently selected item.\nRenders a `<span>` element.",
   "props": {
+    "placeholder": {
+      "type": "ReactNode",
+      "description": "The placeholder value to display when no value is selected.\nThis is overridden by `children` if specified, or by a null item's label in `items`.",
+      "detailedType": "React.ReactNode"
+    },
     "children": {
       "type": "ReactNode | ((value: any) => ReactNode)",
       "description": "Accepts a function that returns a `ReactNode` to format the selected value.",

docs/src/app/(docs)/react/components/combobox/demos/hero/css-modules/index.tsx

@@ -27,12 +27,12 @@ export default function ExampleCombobox() {
           <Combobox.Popup className={styles.Popup}>
             <Combobox.Empty className={styles.Empty}>No fruits found.</Combobox.Empty>
             <Combobox.List className={styles.List}>
-              {(item: string) => (
-                <Combobox.Item key={item} value={item} className={styles.Item}>
+              {(item: Fruit) => (
+                <Combobox.Item key={item.value} value={item} className={styles.Item}>
                   <Combobox.ItemIndicator className={styles.ItemIndicator}>
                     <CheckIcon className={styles.ItemIndicatorIcon} />
                   </Combobox.ItemIndicator>
-                  <div className={styles.ItemText}>{item}</div>
+                  <div className={styles.ItemText}>{item.label}</div>
                 </Combobox.Item>
               )}
             </Combobox.List>
@@ -86,30 +86,35 @@ function ChevronDownIcon(props: React.ComponentProps<'svg'>) {
   );
 }
 
-const fruits = [
-  'Apple',
-  'Banana',
-  'Orange',
-  'Pineapple',
-  'Grape',
-  'Mango',
-  'Strawberry',
-  'Blueberry',
-  'Raspberry',
-  'Blackberry',
-  'Cherry',
-  'Peach',
-  'Pear',
-  'Plum',
-  'Kiwi',
-  'Watermelon',
-  'Cantaloupe',
-  'Honeydew',
-  'Papaya',
-  'Guava',
-  'Lychee',
-  'Pomegranate',
-  'Apricot',
-  'Grapefruit',
-  'Passionfruit',
+interface Fruit {
+  label: string;
+  value: string;
+}
+
+const fruits: Fruit[] = [
+  { label: 'Apple', value: 'apple' },
+  { label: 'Banana', value: 'banana' },
+  { label: 'Orange', value: 'orange' },
+  { label: 'Pineapple', value: 'pineapple' },
+  { label: 'Grape', value: 'grape' },
+  { label: 'Mango', value: 'mango' },
+  { label: 'Strawberry', value: 'strawberry' },
+  { label: 'Blueberry', value: 'blueberry' },
+  { label: 'Raspberry', value: 'raspberry' },
+  { label: 'Blackberry', value: 'blackberry' },
+  { label: 'Cherry', value: 'cherry' },
+  { label: 'Peach', value: 'peach' },
+  { label: 'Pear', value: 'pear' },
+  { label: 'Plum', value: 'plum' },
+  { label: 'Kiwi', value: 'kiwi' },
+  { label: 'Watermelon', value: 'watermelon' },
+  { label: 'Cantaloupe', value: 'cantaloupe' },
+  { label: 'Honeydew', value: 'honeydew' },
+  { label: 'Papaya', value: 'papaya' },
+  { label: 'Guava', value: 'guava' },
+  { label: 'Lychee', value: 'lychee' },
+  { label: 'Pomegranate', value: 'pomegranate' },
+  { label: 'Apricot', value: 'apricot' },
+  { label: 'Grapefruit', value: 'grapefruit' },
+  { label: 'Passionfruit', value: 'passionfruit' },
 ];

docs/src/app/(docs)/react/components/combobox/demos/hero/tailwind/index.tsx

@@ -38,16 +38,16 @@ export default function ExampleCombobox() {
               No fruits found.
             </Combobox.Empty>
             <Combobox.List className="outline-0 overflow-y-auto scroll-py-[0.5rem] py-2 overscroll-contain max-h-[min(23rem,var(--available-height))] data-[empty]:p-0">
-              {(item: string) => (
+              {(item: Fruit) => (
                 <Combobox.Item
-                  key={item}
+                  key={item.value}
                   value={item}
                   className="grid cursor-default grid-cols-[0.75rem_1fr] items-center gap-2 py-2 pr-8 pl-4 text-base leading-4 outline-none select-none data-[highlighted]:relative data-[highlighted]:z-0 data-[highlighted]:text-gray-50 data-[highlighted]:before:absolute data-[highlighted]:before:inset-x-2 data-[highlighted]:before:inset-y-0 data-[highlighted]:before:z-[-1] data-[highlighted]:before:rounded-sm data-[highlighted]:before:bg-gray-900"
                 >
                   <Combobox.ItemIndicator className="col-start-1">
                     <CheckIcon className="size-3" />
                   </Combobox.ItemIndicator>
-                  <div className="col-start-2">{item}</div>
+                  <div className="col-start-2">{item.label}</div>
                 </Combobox.Item>
               )}
             </Combobox.List>
@@ -101,30 +101,35 @@ function ChevronDownIcon(props: React.ComponentProps<'svg'>) {
   );
 }
 
-const fruits = [
-  'Apple',
-  'Banana',
-  'Orange',
-  'Pineapple',
-  'Grape',
-  'Mango',
-  'Strawberry',
-  'Blueberry',
-  'Raspberry',
-  'Blackberry',
-  'Cherry',
-  'Peach',
-  'Pear',
-  'Plum',
-  'Kiwi',
-  'Watermelon',
-  'Cantaloupe',
-  'Honeydew',
-  'Papaya',
-  'Guava',
-  'Lychee',
-  'Pomegranate',
-  'Apricot',
-  'Grapefruit',
-  'Passionfruit',
+interface Fruit {
+  label: string;
+  value: string;
+}
+
+const fruits: Fruit[] = [
+  { label: 'Apple', value: 'apple' },
+  { label: 'Banana', value: 'banana' },
+  { label: 'Orange', value: 'orange' },
+  { label: 'Pineapple', value: 'pineapple' },
+  { label: 'Grape', value: 'grape' },
+  { label: 'Mango', value: 'mango' },
+  { label: 'Strawberry', value: 'strawberry' },
+  { label: 'Blueberry', value: 'blueberry' },
+  { label: 'Raspberry', value: 'raspberry' },
+  { label: 'Blackberry', value: 'blackberry' },
+  { label: 'Cherry', value: 'cherry' },
+  { label: 'Peach', value: 'peach' },
+  { label: 'Pear', value: 'pear' },
+  { label: 'Plum', value: 'plum' },
+  { label: 'Kiwi', value: 'kiwi' },
+  { label: 'Watermelon', value: 'watermelon' },
+  { label: 'Cantaloupe', value: 'cantaloupe' },
+  { label: 'Honeydew', value: 'honeydew' },
+  { label: 'Papaya', value: 'papaya' },
+  { label: 'Guava', value: 'guava' },
+  { label: 'Lychee', value: 'lychee' },
+  { label: 'Pomegranate', value: 'pomegranate' },
+  { label: 'Apricot', value: 'apricot' },
+  { label: 'Grapefruit', value: 'grapefruit' },
+  { label: 'Passionfruit', value: 'passionfruit' },
 ];

docs/src/app/(docs)/react/components/combobox/demos/input-inside-popup/css-modules/index.module.css

@@ -1,3 +1,10 @@
+.Field {
+  display: flex;
+  flex-direction: column;
+  align-items: start;
+  gap: 0.25rem;
+}
+
 .Trigger {
   box-sizing: border-box;
   display: flex;
@@ -41,6 +48,10 @@
   display: flex;
 }
 
+.Placeholder {
+  opacity: 0.6;
+}
+
 .InputContainer {
   box-sizing: border-box;
   width: 20rem;
@@ -71,9 +82,6 @@
 }
 
 .Label {
-  display: flex;
-  flex-direction: column;
-  gap: 0.25rem;
   font-size: 0.875rem;
   line-height: 1.25rem;
   font-weight: 500;

docs/src/app/(docs)/react/components/combobox/demos/input-inside-popup/css-modules/index.tsx

@@ -1,38 +1,44 @@
 'use client';
 import * as React from 'react';
 import { Combobox } from '@base-ui/react/combobox';
+import { Field } from '@base-ui/react/field';
 import styles from './index.module.css';
 
 export default function ExamplePopoverCombobox() {
   return (
-    <Combobox.Root items={countries} defaultValue={countries[0]}>
-      <Combobox.Trigger className={styles.Trigger}>
-        <Combobox.Value />
-        <Combobox.Icon className={styles.TriggerIcon}>
-          <ChevronUpDownIcon />
-        </Combobox.Icon>
-      </Combobox.Trigger>
-      <Combobox.Portal>
-        <Combobox.Positioner align="start" sideOffset={4}>
-          <Combobox.Popup className={styles.Popup} aria-label="Select country">
-            <div className={styles.InputContainer}>
-              <Combobox.Input placeholder="e.g. United Kingdom" className={styles.Input} />
-            </div>
-            <Combobox.Empty className={styles.Empty}>No countries found.</Combobox.Empty>
-            <Combobox.List className={styles.List}>
-              {(country: Country) => (
-                <Combobox.Item key={country.code} value={country} className={styles.Item}>
-                  <Combobox.ItemIndicator className={styles.ItemIndicator}>
-                    <CheckIcon className={styles.ItemIndicatorIcon} />
-                  </Combobox.ItemIndicator>
-                  <div className={styles.ItemText}>{country.label ?? country.value}</div>
-                </Combobox.Item>
-              )}
-            </Combobox.List>
-          </Combobox.Popup>
-        </Combobox.Positioner>
-      </Combobox.Portal>
-    </Combobox.Root>
+    <Field.Root className={styles.Field}>
+      <Field.Label className={styles.Label}>Country</Field.Label>
+      <Combobox.Root items={countries}>
+        <Combobox.Trigger className={styles.Trigger}>
+          <Combobox.Value
+            placeholder={<span className={styles.Placeholder}>Select country</span>}
+          />
+          <Combobox.Icon className={styles.TriggerIcon}>
+            <ChevronUpDownIcon />
+          </Combobox.Icon>
+        </Combobox.Trigger>
+        <Combobox.Portal>
+          <Combobox.Positioner align="start" sideOffset={4}>
+            <Combobox.Popup className={styles.Popup} aria-label="Select country">
+              <div className={styles.InputContainer}>
+                <Combobox.Input placeholder="e.g. United Kingdom" className={styles.Input} />
+              </div>
+              <Combobox.Empty className={styles.Empty}>No countries found.</Combobox.Empty>
+              <Combobox.List className={styles.List}>
+                {(country: Country) => (
+                  <Combobox.Item key={country.code} value={country} className={styles.Item}>
+                    <Combobox.ItemIndicator className={styles.ItemIndicator}>
+                      <CheckIcon className={styles.ItemIndicatorIcon} />
+                    </Combobox.ItemIndicator>
+                    <div className={styles.ItemText}>{country.label}</div>
+                  </Combobox.Item>
+                )}
+              </Combobox.List>
+            </Combobox.Popup>
+          </Combobox.Positioner>
+        </Combobox.Portal>
+      </Combobox.Root>
+    </Field.Root>
   );
 }
 
@@ -63,13 +69,12 @@ function CheckIcon(props: React.ComponentProps<'svg'>) {
 
 interface Country {
   code: string;
-  value: string | null;
+  value: string;
   continent: string;
   label: string;
 }
 
 const countries: Country[] = [
-  { code: '', value: null, continent: '', label: 'Select country' },
   { code: 'af', value: 'afghanistan', label: 'Afghanistan', continent: 'Asia' },
   { code: 'al', value: 'albania', label: 'Albania', continent: 'Europe' },
   { code: 'dz', value: 'algeria', label: 'Algeria', continent: 'Africa' },