[Autocomplete] Add ability to render custom single value

[ZeeshanTamboli]

Closes #26440

Based on the upvotes and requests in #26440, this PR introduces a new renderSingleValue prop to customize the display of the selected value. This is separate from renderTags for clarity. I avoided naming it renderTag to prevent potential confusion and typos.

Preview: https://deploy-preview-45387--material-ui.netlify.app/material-ui/react-autocomplete/#custom-single-value-rendering

[mui-bot]

Netlify deploy preview

• docs/data/material/components/autocomplete/autocomplete.md

@material-ui/core: parsed: +0.07% , gzip: +0.09%
Autocomplete: parsed: +0.23% , gzip: +0.26%

Bundle size report

Details of bundle changes (Toolpad)
Details of bundle changes

Generated by 🚫 dangerJS against 934e57d

[DiegoAndai]

Hey @ZeeshanTamboli, thanks for working on this!

I think the solution is the correct one but I'm wondering what's the best for the API design, the options I see:

• This PR's solution: add a renderSingleValue prop which is only used when multiple={false}
• Add a renderValue prop which works regardless of multiple, and deprecate renderTags in favor of it
• Use slots, like slots.value and slotProps.value
• Other

What do you think @aarongarciah?

[DiegoAndai]

useAutocomplete doesn't return tagProps, did you mean getTagProps?

[ZeeshanTamboli]

It now returns in this PR for a single tag: https://github.com/mui/material-ui/pull/45387/files#diff-a3e15b1f22a8ed2de23c8cee46ea92a1d2828d4718cb471c6404d9baadd2c68fR1154-R1158. Should I rename it to singleTagProps? I avoided get* since it doesn’t need to be a function.

[ZeeshanTamboli]

Hey @ZeeshanTamboli, thanks for working on this!

I think the solution is the correct one but I'm wondering what's the best for the API design, the options I see:

• This PR's solution: add a renderSingleValue prop which is only used when multiple={false}
• Add a renderValue prop which works regardless of multiple, and deprecate renderTags in favor of it
• Use slots, like slots.value and slotProps.value
• Other

I wouldn’t use the slots API since this is passed as startAdornment in the TextField. Also, IMO, combining single and multiple tags in renderValue isn’t ideal—we wouldn’t know if selecting another option should create a new tag (multiple) or replace the existing one (single) unless user passes some config.

[aarongarciah]

I wouldn’t use the slots API since this is passed as startAdornment in the TextField. Also, IMO, combining single and multiple tags in renderValue isn’t ideal—we wouldn’t know if selecting another option should create a new tag (multiple) or replace the existing one (single) unless user passes some config.

@ZeeshanTamboli can you provide a code snippet of how it'd look like if we combined rendering single and multiple values in a single prop like renderValue to highlight the problem you're describing? I'm not sure I fully understand it.

[ZeeshanTamboli]

@ZeeshanTamboli can you provide a code snippet of how it'd look like if we combined rendering single and multiple values in a single prop like renderValue to highlight the problem you're describing? I'm not sure I fully understand it.

@aarongarciah Check out the existing renderTags and the newly introduced renderSingleValue in this PR:

• renderTags (for multiple values):

  renderTags={(tagValue, getTagProps) =>
    tagValue.map((option, index) => {
      const { key, ...tagProps } = getTagProps({ index });
      return (
        <Chip
          key={key}
          label={option.title}
          {...tagProps}
        />
      );
    })
  }

• renderSingleValue (for a single value):

  renderSingleValue={(value, singleTagProps) => (
    <Chip label={value.title} {...singleTagProps} />
  )}

If we were to combine them into a single renderValue prop, it would introduce complexity:

1. The values parameter would need to handle both single values (string/object) and multiple values (array).
2. In TypeScript, developers would need to narrow down the type first to manually distinguish between one of the two cases:

renderValue={(values, getTagProps) => {
  if (Array.isArray(values)) {
    return values.map((val, index) => {
      const { key, ...tagProps } = getTagProps({ index });
      return <Chip key={key} label={val.title} {...tagProps} />;
    });
  }
  return <Chip label={values.title} />;
}}

3. For multiple values, users must pass the current index to getTagProps, while for a single value, no index is needed.

I think it's possible but adds complexity. To avoid point 2 above, we'd need a conditional generic type based on multiple={true} and add logic everywhere based on multiple being present or not to pass either an array or a single value to renderValue. What do you think?

[aarongarciah]

@ZeeshanTamboli thanks for the explanation. What I find weird is that users can use renderSingleValue and return a string but get a totally different behavior than using getOptionLabel: the former injects something in the startAdornment while the latter is the input value. I think the renderSingleValue name can cause confusion.

Although there's no concept of "tags" in single selection mode by default in the Autocomplete (i.e. single values are represented as plain text in the input), I think renderTags and renderSingleValue are doing the same thing: rendering "rich" content for the value/s. Having two separate props feels odd.

Would it make sense for renderTags to always provide an array as the first argument no matter if the Autocomplete is in single or multiple mode so users could always use this prop? Would it be weird? renderTags would take precedence in single mode over getOptionLabel.

I have doubts about the best path forward. Let's not rush this since it's important to keep the Autocomplete API at a minimum (it's large enough already) and a workaround exists (not ideal though).

[DiegoAndai]

Would it make sense for renderTags to always provide an array as the first argument no matter if the Autocomplete is in single or multiple mode so users could always use this prop? Would it be weird? renderTags would take precedence in single mode over getOptionLabel.

This idea makes sense to me. I would rename it to renderValue and deprecate renderTags in favor of it though.

[ZeeshanTamboli]

I'll try it out. Let's see how it pans out.

[ZeeshanTamboli]

@aarongarciah @DiegoAndai Based on the discussion, the renderValue API would work like this:

For single value, when multiple isn't provided:

renderValue={(tagValue, getTagProps) => (
  <Chip label={tagValue[0].title} {...getTagProps()} />
)}

Note that label is accessed from tagValue[0] since value is always an array, even for single selection, and index isn't needed for getTagProps.

---

For multiple values (same as before):

renderValue={(tagValue, getTagProps) =>
  tagValue.map((option, index) => (
    <Chip
      key={getTagProps({ index }).key}
      label={option.title}
      {...getTagProps({ index })}
    />
  ))
}

Should I go ahead and make the changes?

[aarongarciah]

@ZeeshanTamboli looks good! I wonder if it should be called renderValues instead, since the value is always an array. Also, I think we need to come up with a better name in our examples for tagValue / getTagProps. Maybe item / getItemProps works? cc @DiegoAndai

Also cc @michaldudak in case you have some feedback.

[michaldudak]

I wonder if it wouldn't be possible to have the type of the parameter depend on the Autocomplete's multiple prop (so it's an array only when multiple = true). The props already are generic over Multiple, so it should be doable.