[docs][autocomplete] Confusing TypeScript inference section

[ZeeshanTamboli]

Docs feedback

How can we improve Base UI documentation?

The documentation at
https://base-ui.com/react/components/autocomplete#typescript-inference
currently states:

If using itemToStringValue, the value prop on the <Autocomplete.Item> must match the type of an item in the items array.

This wording is potentially misleading. The value prop on <Autocomplete.Item> must always match the item type from the items array passed to <Autocomplete.Root>, regardless of whether itemToStringValue is used.

In other words, itemToStringValue does not change the expected type of value., it only affects how items are displayed and matched. TypeScript already enforces this constraint even when itemToStringValue is not provided, as can be seen in the Autocomplete hero demo, which does not use itemToStringValue but still passes items of the same type to value.

Because this rule is unconditional, the sentence above appears unnecessary and may imply that the constraint only applies when itemToStringValue is used. Removing it (or rephrasing it as a general clarification) would make the TypeScript inference section more accurate and less confusing.

[CiscoFran10]

One possible way to clarify the section would be to rephrase it along these lines:

Autocomplete infers the item type from the items prop passed to <Autocomplete.Root>. The value prop on <Autocomplete.Item> must always match the type of an item in the items array.

The itemToStringValue prop can be used to control how items are converted to strings for display and text matching (for example, when items are objects or when multiple fields should be combined).

This keeps the type requirement explicit while explaining what itemToStringValue is actually responsible for.

[atomiks]

It's right to an extent: you can pass value={tag.value} in the hero demo, and it still works — provided value/label don't need to be differentiated

Since Combobox doesn't support this (value/defaultValue currently must match the items type for some internal operations), it's probabably still worth changing the wording to imply that they must match so that itemToStringValue has correct inference

[ZeeshanTamboli]

Since Combobox doesn't support this (value/defaultValue currently must match the items type for some internal operations), it's probabably still worth changing the wording to imply that they must match so that itemToStringValue has correct inference

Sorry, I didn't understand this. What would you suggest the wording to be?

[ZeeshanTamboli]

One possible way to clarify the section would be to rephrase it along these lines:

Autocomplete infers the item type from the items prop passed to <Autocomplete.Root>. The value prop on <Autocomplete.Item> must always match the type of an item in the items array.
The itemToStringValue prop can be used to control how items are converted to strings for display and text matching (for example, when items are objects or when multiple fields should be combined).

This keeps the type requirement explicit while explaining what itemToStringValue is actually responsible for.

But then it's better to not include what itemToStringValue prop is used for under "TypeScript inference" section if it is not related to TS.