[select] Refine `Select.Value` `placeholder` API

[atomiks]

Feature request

Summary

Currently <Select.Value placeholder="" /> represents the "initial" label before an item has been chosen, even if one was initially chosen on mount. It therefore conflates text shown when value == null, and the value during SSR pre-rendering (and now, in beta.0, before the popup is opened to grab the labels based on the default value).

Motivation

placeholder should only represent value == null, while the initial label when defaultValue or value is pre-selected (during SSR/client pre-mount) must be distinguished to prevent confusion.

In alpha.8, it only affected SSR pre-rendering (it was blank before hydration), but now with the perf improvements to Select, it also affects client rendering too (so it's always blank). As a result we made placeholder required instead of optional. Either way it must be specified manually.

[atomiks]

The placeholder prop conflates an "initial" label (due to SSR and pre-mount limitations) with text shown when value == null

Initial label (default value)

Case 1: Default value, never a placeholder

<Select.Root defaultValue="red">
  <Select.Value placeholder="Red" /> {/* SSR/pre-mount label */}
  <Select.Portal>
    <Select.Positioner>
      <Select.Popup>
        <Select.Item value="red">
          Red
        </Select.Item>
      </Select.Popup>
    </Select.Positioner>
  </Select.Portal>
</Select.Root>

Case 2: Default value, can change to an empty value

<Select.Root defaultValue="red">
  <Select.Value placeholder="Red" /> {/* SSR/pre-mount label */}
  <Select.Portal>
    <Select.Positioner>
      <Select.Popup>
        <Select.Item>
          Select value {/* Acts as the placeholder */}
        </Select.Item>
        <Select.Item value="red">
          Red
        </Select.Item>
      </Select.Popup>
    </Select.Positioner>
  </Select.Portal>
</Select.Root>

Placeholder label (empty value)

Case 3: No default value, cannot revert back after selection

<Select.Root>
  <Select.Value placeholder="Select value" /> {/* SSR/pre-mount label, can't revert back */}
  <Select.Portal>
    <Select.Positioner>
      <Select.Popup>
        <Select.Item value="red">
          Red
        </Select.Item>
      </Select.Popup>
    </Select.Positioner>
  </Select.Portal>
</Select.Root>

Case 4: No default value, but can revert back after selection

<Select.Root>
  <Select.Value placeholder="Select value" /> {/* SSR/pre-mount label */}
  <Select.Portal>
    <Select.Positioner>
      <Select.Popup>
        <Select.Item> {/* null value by default */}
          Select value {/* Same as `placeholder` */}
        </Select.Item>
        <Select.Item value="red">
          Red
        </Select.Item>
      </Select.Popup>
    </Select.Positioner>
  </Select.Portal>
</Select.Root>

---

Possible API:

Split placeholder into two props:

• defaultLabel
• placeholder

For case 1 and 2, defaultLabel is specified, but not placeholder.
For case 3 and 4, placeholder is specified, but not defaultLabel.

[atomiks]

Another issue pointed out by @colmtuite: placeholder as a concept should be a hint to the expected data type, not a verb like Enter input or Select value.

https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/placeholder

Effective placeholder text includes a word or short phrase that hints at the expected data type, not an explanation or prompt. The placeholder must not be used instead of a label. As the placeholder is not visible if the value of the form control is not null, using placeholder instead of a for a prompt harms usability and accessibility.

And another point dicussed: Since Select.Value prints the label not the raw value, Select.DisplayValue may be a more appropriate component name.

[janroest]

That is actually huge. I had to remove the select and did go back to radix for this.

[atomiks]

@janroest Sorry, I understand this placeholder API is confusing 😓 but it works the same as it did before in alpha.8.

If you didn't specify placeholder before, the value was empty before hydration and led to a flash, so it was partially broken before anyway if you omitted it (it was just less obvious/troublesome).

If you have an initial value, all you need to do is specify what the Select.ItemText is for the given value (e.g. placeholder="Label for initial value"), and it works as before while also handling SSR.

[github-actions]

This feature will be available in the next npm release of Base UI.

In the meantime, you can try it out on our Canary release channel:

npm i https://pkg.pr.new/@base-ui-components/react@2087