Autocomplete | Calcite Design System

Autocomplete facilitates the selection of a single item from a list of suggestions.

Overview

Autocomplete offers users the ability to find a single option from a list of items, such as an address. When users type, live suggestions are provided allowing users to select their desired option.

Autocomplete relies on custom configuration and logic to support filtering, state, and selection. These capabilities are not built in and must be implemented in application logic.

Sample

Usage

Filtering and searching long lists
Returning items to a user based on input

Component comparison

While visually similar to the Combobox, the Autocomplete component has distinct capabilities and intended use cases.

Autocomplete

This component

Often used to select from very large or dynamic sets of items.

Custom configuration and logic is needed to support filtering, state, and selection.

Supports single selection.

Combobox

Alternative

Often used to select from known sets of items.

Includes built-in filtering, state, selection, and custom item creation.

Supports various selectionMode options, including single and multiple selection.

Best practices

Recommendations

Do use Autocomplete when there are an unknown or large number of items or records.

Do use Autocomplete when the user can select a single choice.

Avoid using Autocomplete for a known, small number of records.

Avoid using Autocomplete when there is a need to select multiple items.

Accessibility

Key	Function
`Backspace`	When the component is focused and contains a selected `calcite-autocomplete-item` will remove the most recently added from the component.
`Space`	If the component is not `open`, opens the component.
`Arrow up`	If the component is `open` and in focus, moves focus to previous `calcite-autocomplete-item`. If the current focus is the first `calcite-autocomplete-item`.
`Arrow down`	If the component is `open` and in focus, move focus to next `calcite-autocomplete-item`. If the current focus is the last `calcite-autocomplete-item`, focus will cycle to the first `calcite-autocomplete-item`.
`Enter`	If the component is open and a `calcite-autocomplete-item` is `active`, will select the item.
`Esc`	If the component is `open`, closes the component.
`Tab`	Moves focus in and out of the component. If the component is not `open` and `calcite-autocomplete-item`s are present, the component will open. If the component is `open`, the component will close.
`Tab` and `Shift`	Moves focus in and out of the component. If the component is not `open` and `calcite-autocomplete-item`'s are present, the component will open. If the component is `open`, the component will close.
`Home`	Moves focus to the first `calcite-autocomplete-item`, if present. If the component is not `open` and `calcite-autocomplete-item`'s are present, the component will open.
`End`	Moves focus to the last `calcite-autocomplete-item`, if present. If the component is not `open` and `calcite-autocomplete-item`'s are present, the component will open. If the component is `open`, the component will close.

API reference

Properties

Property	Attribute	Description	Type	Default
alignment	alignment	Specifies the text alignment of the component's value.	`Extract<"start" \| "end", Alignment>`	`"start"`
autocomplete	autocomplete	Specifies the type of content to autocomplete, for use in forms. Read the native attribute's documentation on MDN for more info.	`AutoFill`
disabled	disabled	When `true`, interaction is prevented and the component is displayed with lower opacity.	`boolean`	`false`
flipPlacements		Specifies the component's fallback `placement` for slotted content when it's initial or specified `placement` has insufficient space available.	`FlipPlacement[]`
form	form	Specifies the `id` of the component's associated form. When not set, the component is associated with its ancestor form element, if one exists.	`string`
icon	icon	When `true` or not set, shows a default recommended icon. Alternatively, pass a Calcite UI Icon name to display a specific icon. To hide the default icon, set the property to `false` using JavaScript.	`IconName \| boolean`
iconFlipRtl	icon-flip-rtl	When `true`, the icon will be flipped when the element direction is right-to-left (`"rtl"`).	`boolean`	`false`
inputValue	input-value	Specifies the text typed into the component and is used to filter slotted `autocomplete-item`s.	`string`
label	label	Specifies an accessible label for the component.	`string`
labelText	label-text	Specifies the component's label text.	`string`
loading	loading	When `true`, a busy indicator is displayed.	`boolean`	`false`
maxLength	max-length	When the component resides in a form, specifies the maximum length of text for the component's value.	`number`
messageOverrides		Overrides individual strings used by the component.	`Record<string, unknown> \| undefined`
minLength	min-length	When the component resides in a form, specifies the minimum length of text for the component's value.	`number`
name	name	Specifies the name of the component. Required to pass the component's `value` on form submission.	`string`
open	open	When `true`, displays and positions the component.	`boolean`	`false`
overlayPositioning	overlay-positioning	Specifies the type of positioning to use for overlaid content, where: `"absolute"` works for most cases - positioning the component inside of overflowing parent containers, which affects the container's layout, and `"fixed"` is used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`.	`OverlayPositioning`	`"absolute"`
pattern	pattern	When the component resides in a form, specifies a regular expression (regex) pattern the component's `value` must match for validation. Read the native attribute's documentation on MDN for more info.	`string`
placeholder	placeholder	Specifies placeholder text for the component.	`string`
placement	placement	Determines where the component will be positioned relative to the container element.	`MenuPlacement`	`"bottom-start"`
prefixText	prefix-text	Specifies the component's prefix text.	`string`
readOnly	read-only	When `true`, the component's value can be read, but cannot be modified.	`boolean`	`false`
required	required	When `true` and the component resides in a form, the component must have a value in order for the form to submit.	`boolean`	`false`
scale	scale	Specifies the size of the component.	`Scale`	`"m"`
status	status	Specifies the status of the input field, which determines message and icons.	`Status`	`"idle"`
suffixText	suffix-text	Specifies the component's suffix text.	`string`
topLayerDisabled	top-layer-disabled	When `true` and the component is `open`, disables top layer placement. Only set this if you need complex z-index control or if top layer placement causes conflicts with third-party components.	`boolean`	`false`
validationIcon	validation-icon	Specifies the validation icon to display under the component.	`IconName \| boolean`
validationMessage	validation-message	Specifies the validation message to display under the component.	`string`
validityread-only		The component's current validation state.	`ValidityState`
value	value	Specifies the selected `autocomplete-item`. When the component resides in a form, the `value` is submitted with the form.	`string`	`""`

Slots

Name	Description
default (unnamed)	A slot for adding `calcite-autocomplete-item` elements.
content-bottom	A slot for adding content below `calcite-autocomplete-item` elements.
content-top	A slot for adding content above `calcite-autocomplete-item` elements.
label-content	A slot for rendering content next to the component's `labelText`.

Styles

Name	Description
--calcite-autocomplete-background-color	Specifies the component's background color.
--calcite-autocomplete-corner-radius	Specifies the component's corner radius.
--calcite-autocomplete-text-color	Specifies the component's text color.
--calcite-autocomplete-menu-max-size-y	Specifies the maximum height of the component's menu.
--calcite-autocomplete-input-prefix-size	Specifies the input's prefix width, when present.
--calcite-autocomplete-input-suffix-size	Specifies the input's suffix width, when present.
--calcite-autocomplete-input-background-color	Specifies the background color of the component's input.
--calcite-autocomplete-input-border-color	Specifies the border color of the component's input.
--calcite-autocomplete-input-corner-radius	Specifies the corner radius of the component's input.
--calcite-autocomplete-input-shadow	Specifies the shadow of the component's input.
--calcite-autocomplete-input-icon-color	Specifies the icon color of the component's input.
--calcite-autocomplete-input-text-color	Specifies the text color of the component's input.
--calcite-autocomplete-input-placeholder-text-color	Specifies the placeholder text color of the component's input.
--calcite-autocomplete-input-actions-background-color	Specifies the background color of the input's `clearable` element.
--calcite-autocomplete-input-actions-background-color-hover	Specifies the background color of the input's `clearable` element when hovered.
--calcite-autocomplete-input-actions-background-color-press	Specifies the background color of the input's `clearable` element when pressed.
--calcite-autocomplete-input-actions-icon-color	Specifies the icon color of the input's `clearable` element.
--calcite-autocomplete-input-actions-icon-color-hover	Specifies the icon color of the input's `clearable` element when hovered.
--calcite-autocomplete-input-actions-icon-color-press	Specifies the icon color of the input's `clearable` element when pressed.
--calcite-autocomplete-input-loading-background-color	Specifies the background color of the Input's `loading` element, when present.
--calcite-autocomplete-input-loading-fill-color	Specifies the fill color of the Input's `loading` element, when present.
--calcite-autocomplete-input-prefix-text-color	Specifies the text color of the Input's prefix, when present.
--calcite-autocomplete-input-suffix-text-color	Specifies the text color of the Input's suffix, when present.

Events

Name	Description	Behavior
calciteAutocompleteBeforeClose	Fires when the component is requested to be closed and before the closing transition begins.	bubblescomposed
calciteAutocompleteBeforeOpen	Fires when the component is added to the DOM but not rendered, and before the opening transition begins.	bubblescomposed
calciteAutocompleteChange	Fires each time a new `value` is typed and committed.	bubblescomposed
calciteAutocompleteClose	Fires when the component is closed and animation is complete.	bubblescomposed
calciteAutocompleteOpen	Fires when the component is open and animation is complete.	bubblescomposed
calciteAutocompleteTextChange	Fires each time a new `inputValue` is typed and committed.	bubblescomposed
calciteAutocompleteTextInput	Fires each time a new `inputValue` is typed.	bubblescomposed

Methods

Name	Description	Signature
componentOnReady	Creates a promise that resolves once the component is fully loaded.	`componentOnReady(): Promise<this>`
reposition	Updates the position of the component.	`reposition(delayed?: boolean): Promise<void>`
scrollContentTo	Scrolls the component's content to a specified set of coordinates.	`scrollContentTo(options?: ScrollToOptions): Promise<void>`
selectText	Selects the text of the component's `value`.	`selectText(): Promise<void>`
setFocus	Sets focus on the component's first focusable element.	`setFocus(options?: FocusOptions): Promise<void>`