An enhanced input that provides a list of suggested options.
Best Practices
An Autocomplete is recommended when a list of possible options is too extensive to be handled by a native select.
There are two primary scenarios:
An exact match is required from a list of options for data validity
A user's free text entry may be accepted, but it's best if they select from a predefined list
Basic Autocomplete
The Autocomplete extends from TextField and accepts all of it's properties in addition to it's own unique ones. The following are the required props:
id - ensures all accessibility features work
label - also required for accessibility
options - expects a pre-sorted, flat array of strings
By default, results begin showing after 3 characters, which you may change with the minCharacters prop.
()=>{
const options =[
'Strawberry',
'Blackberry',
'Blueberry',
'Blueberry Pie',
'Elderberry',
'Snozberry',
'Chocoberry',
'Razzleberry',
'Gooseberry',
'Jamberry',
'Pinkberry'
];
return(
<Gridcontainerspacing={6}component="form">
<Griditemmd={8}>
<Autocompleteid="autocomplete"label="Select a berry"options={options}/>
</Grid>
<Griditemmd={8}>
<Autocomplete
id="autocomplete-filled"
variant="filled"
label="Select a berry"
options={options}
/>
</Grid>
<Griditemmd={8}>
<Autocomplete
id="autocomplete-standard"
variant="standard"
label="Select a berry"
options={options}
/>
</Grid>
</Grid>
);
};
This version adds help text and removes the minimum character requirement.
()=>{
const options =[
'Strawberry',
'Blackberry',
'Blueberry',
'Blueberry Pie',
'Elderberry',
'Snozberry',
'Chocoberry',
'Razzleberry',
'Gooseberry',
'Jamberry',
'Pinkberry',
];
return(
<Autocomplete
id="autocomplete"
label="Select a berry"
helperText='Begin typing "ber"'
minCharacters={0}
options={options}
/>
);
};
Options from Object Arrays
An object array may be passed instead of a string array as long as it is coupled with the optionDisplayFieldKeys property to define at minimum the primary key, and optionally the secondary key.
Note: The primary value will ultimately be selected and used as the input's value and therefore be what's included in a form submission and available to be checked by validation.
The default filter function will search both fields based on the user's input.
This method is useful if the underlying data structure cannot be manipulated to allow you to designate which key/value pairs to use for the Autocomplete list display.
The default filter function will do a simple string compare to find the user's input within any part of the options full value, meaning partial matches are included (hence the ability in the earlier demo to enter "ber" to get any berries as match possibilities).
You can also pass a custom filter function, which can be particularly useful if the data being searched is an object of multiple key/value pairs to allow searching in more than one field.
The demo creates a custom filter to only search in one field even though two object fields are displayed.
// Only return matches based on the loan_id field, not both
return opts.filter((opt)=>{
return`${opt.loan_id}`.match(valuePattern);
});
}}
/>
);
};
onChange and Error Handling
The onChange event emits the updated value as the second parameter. In this example, this is used to trigger an error state and message if the user attempts a value not available in the provided list of options.
Note: onBlur and onFocus receive just the event, where the value can be obtained from event.target.value.