[RFC] Add composable start and end adornments to Autocomplete

[ZeeshanTamboli]

What's the problem?

Autocomplete uses the input's adornment positions for its own UI:

• Selected values and chips are passed through params.slotProps.input.startAdornment.
• The clear and popup indicators are passed through params.slotProps.input.endAdornment.

When users provide a custom adornment inside renderInput, React replaces the corresponding internal adornment. This can hide selected values, remove built-in controls, or break interactions.

The current workaround requires users to understand and preserve Autocomplete's internal render parameters:

startAdornment: (
  <>
    {customStartAdornment}
    {params.slotProps.input.startAdornment}
  </>
)

This behavior has led to repeated reports across several major versions, including #19479, #22103, and #45494. It has also become more visible during the migration from InputProps to slotProps.

The desired outcome is a additive API for custom adornments:

<Autocomplete
  startAdornment={
    <InputAdornment position="start">
      <SearchIcon />
    </InputAdornment>
  }
  endAdornment={
    <InputAdornment position="end">
      <CustomAction />
    </InputAdornment>
  }
  renderInput={(params) => <TextField {...params} />}
/>

Autocomplete would compose these with its internal content:

Start: [custom start] [selected values] [input]
End:   [input] [custom end] [clear indicator] [popup indicator]

What are the requirements?

• Add startAdornment and endAdornment props to Autocomplete.

• Accept any React.ReactNode, consistent with Material UI input components.

• Treat both props as additive rather than replacements for Autocomplete's internal UI.

• Render the custom start adornment before selected values or chips.

• Render the custom end adornment before the clear and popup indicators.

• Render a custom adornment even when there is no corresponding internal adornment.

• Support theme default props through MuiAutocomplete.

What are our options?

Add additive startAdornment and endAdornment props:

interface AutocompleteProps {
  /**
   * Content rendered before the selected values and input.
   */
  startAdornment?: React.ReactNode;

  /**
   * Content rendered before the clear and popup indicators.
   */
  endAdornment?: React.ReactNode;
}

Internally, Autocomplete would keep the generated selected-value adornment separate until after limitTags has been applied:

const composedStartAdornment =
  startAdornmentProp || renderedValueAdornment ? (
    <>
      {startAdornmentProp}
      {renderedValueAdornment}
    </>
  ) : null;

const composedEndAdornment =
  endAdornmentProp || builtInEndAdornment ? (
    <>
      {endAdornmentProp}
      {builtInEndAdornment}
    </>
  ) : null;

These composed nodes would then be provided to renderInput through the existing parameters:

slotProps: {
  input: {
    // Existing required props
    startAdornment: composedStartAdornment,
    endAdornment: composedEndAdornment,
  },
}

Composition must happen after the current limitTags processing because that logic operates on the generated array of selected values.

Why this is preferred

• It directly addresses the common additive use case.
• Users do not need to know which parts of params.slotProps.input contain internal UI.
• It follows the naming used by Material UI's Input and InputBase components.
• It keeps ownership clear: Autocomplete remains responsible for composing selected values and built-in controls.
• It is backward-compatible.
• It remains compatible with renderInput.

Proposed solution

Same as above

Resources and benchmarks

Related issues

• [autocomplete] Cannot use start adornments on multiple select autocomplete #19479
• [autocomplete] InputProps startAdornment incompatibility with multiple #22103
• [autocomplete] Cannot use start adornments on multiple select autocomplete #19479 (comment)

Related pull request

• [docs][autocomplete] Clarify how to render custom start and end adornments #48883

Search keywords: autocomplete, startAdornment, endAdornment, adornment, renderInput

[ZeeshanTamboli]

@siriwatknp @silviuaavram @LukasTy What do you guys think of this proposal?

[siriwatknp]

I think it’s fine to explore & experiment first. I suspect there will be a lot of edge cases alone the way because of the complexity & many scenarios for Autocomplete to handle, e.g. multiple prop. Agree with Lukas

[LukasTy]

Hey @ZeeshanTamboli, this is a nice initiative with a clearly more elegant-looking API.
However, I would urge you to wait a bit for such bigger refactor/simplification changes until some bigger changes in the upcoming major release.