Agriculture Design System
Beta
Design System for the Export Service

Autocomplete

Autocomplete, also known as type-ahead, uses predictive text to help select options as a user types.

View in FigmaView in StorybookView in Github
import { ... } from '@ag.ds-next/react/autocomplete';

Autocomplete helps users by making forms or tasks faster and easier to complete. It is also a feature used in Comboboxes and search tools and bars.

Autocomplete is a controlled component which means consumers of this component need to manage the state of this component by using the value and onChange props.

Open in Playroom, opens in a new tab
() => {
	const [value, setValue] = React.useState(null);
	return (
		<Autocomplete
			label="Find your country"
			hint="Start typing to see results"
			value={value}
			onChange={setValue}
			loadOptions={async function loadOptions(inputValue) {
				// Simulate a slow network call
				await new Promise((resolve) => setTimeout(resolve, 1500));
				return COUNTRY_OPTIONS;
			}}
		/>
	);
};

Do

  • use to help people complete input from an API
  • use for address input
  • use where spelling or data entry might be challenging
  • use to order results in a meaningful way
  • indicate whether input is optional
  • ensure users can easily filter a list of options
  • provide hint text for instruction
  • deliver suggestions in real-time for low latency.

Don’t

  • show more than 10 results at a time
  • use if the list of possible results is small - use Radio instead.

Loading options

Use the loadOptions prop to load options from a remote source as the user types.

This is a function that returns a promise, which is the set of options to be used once the promise resolves.

Block

Use the block prop to expand the component to fill the available space.

Open in Playroom, opens in a new tab
() => {
	const [value, setValue] = React.useState(null);
	return (
		<Autocomplete
			label="Find your country"
			hint="Start typing to see results"
			block
			value={value}
			onChange={setValue}
			loadOptions={async function loadOptions(inputValue) {
				// Simulate a slow network call
				await new Promise((resolve) => setTimeout(resolve, 1500));
				return COUNTRY_OPTIONS;
			}}
		/>
	);
};

Required

The required prop can be used to indicate that user input is required on the field before a form can be submitted.

Using the required prop, this component will automatically append ‘(optional)’ to the label as well as using aria-required to indicate to screen reader users that the field is required.

Hide optional label

The hideOptionalLabel prop can be used in situations where you want to indicate to screen reader users that a field is optional but don’t want to show the ‘(optional)’ label.

The usage of hideOptionalLabel should be reserved for inputs that filter data in a table or chart, and should never be used in standard forms for submitting information.

Open in Playroom, opens in a new tab
() => {
	const [value, setValue] = React.useState(null);
	return (
		<Autocomplete
			label="Find your country"
			hint="Start typing to see results"
			required
			value={value}
			onChange={setValue}
			loadOptions={async function loadOptions(inputValue) {
				// Simulate a slow network call
				await new Promise((resolve) => setTimeout(resolve, 1500));
				return COUNTRY_OPTIONS;
			}}
		/>
	);
};

Invalid

Use the invalid prop to indicate if the user input is invalid.

Open in Playroom, opens in a new tab
() => {
	const [value, setValue] = React.useState(null);
	const invalid = !value;
	return (
		<Autocomplete
			label="Find your country"
			hint="Start typing to see results"
			invalid={invalid}
			message={invalid ? 'State is required' : undefined}
			value={value}
			onChange={setValue}
			loadOptions={async function loadOptions(inputValue) {
				// Simulate a slow network call
				await new Promise((resolve) => setTimeout(resolve, 1500));
				return COUNTRY_OPTIONS;
			}}
		/>
	);
};

Disabled

Disabled input elements are unusable and can not be clicked. This prevents a user from interacting with the input element until another action is complete.

Open in Playroom, opens in a new tab
() => {
	const [value, setValue] = React.useState(null);
	return (
		<Autocomplete
			label="Find your country"
			hint="Start typing to see results"
			disabled
			value={value}
			onChange={setValue}
			loadOptions={async function loadOptions(inputValue) {
				// Simulate a slow network call
				await new Promise((resolve) => setTimeout(resolve, 1500));
				return COUNTRY_OPTIONS;
			}}
		/>
	);
};

Custom rendering

Use the renderItem prop to customise how each option in the dropdown list is rendered. Inside this function, you can make use of the AutocompleteRenderItem component to style extra information.

Note: When you are using this prop, you still need to assign a label and value to every option.

Open in Playroom, opens in a new tab
() => {
	const [value, onChange] = React.useState(null);
	return (
		<Autocomplete
			label="Search users"
			value={value}
			onChange={onChange}
			loadOptions={async function loadOptions() {
				// Simulate a slow network connection
				await new Promise((resolve) => setTimeout(resolve, 1000));
				return NAME_OPTIONS;
			}}
			renderItem={(item, inputValue) => (
				<AutocompleteRenderItem
					itemLabel={item.label}
					inputValue={inputValue}
					secondaryText={`Role: ${item.jobTitle}`}
					tertiaryText={`Job: ${item.status}`}
					beforeElement={
						<Avatar name={item.fullName} size="sm" tone="action" />
					}
					endElement={
						item.unreadMessageCount > 0 ? (
							<NotificationBadge
								value={item.unreadMessageCount}
								tone="action"
							/>
						) : null
					}
				/>
			)}
		/>
	);
};
  • Combobox – This component allows users to select from a list of options. It’s especially useful when there are many options to choose from.
  • Text input – This component allows users to enter free-form text.
Edit this page