Autocomplete

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

Overview

Autocomplete relies on developers to provide a list of suggestions to the user. The user can then select a single suggestion from the list.

Usage

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

Sample

3 samples
1
2
3
4
5
6
7
<calcite-autocomplete name="fruits" placeholder="Select a fruit">
    <calcite-autocomplete-item value="apple" heading="Apple"></calcite-autocomplete-item>
    <calcite-autocomplete-item value="banana" heading="Banana"></calcite-autocomplete-item>
    <calcite-autocomplete-item value="cherry" heading="Cherry"></calcite-autocomplete-item>
    <calcite-autocomplete-item value="date" heading="Date"></calcite-autocomplete-item>
    <calcite-autocomplete-item value="elderberry" heading="Elderberry"></calcite-autocomplete-item>
</calcite-autocomplete>
v3.0.3

Best practices

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

Comparison

AutocompleteThis component
Most often used with very long or unpredictable lengths of items.
Best for programmatically returning responses based on user input.
Does not accept custom values or multiple selections.
ComboboxAlternative
Most often used when the workflow requires multiple selections.
Best when the number of selectable items is finite and small.
Often used for accepting custom values and both single and multiple selection .

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

Keyboard navigation

KeyFunction
BackspaceWhen the component is focused and contains a selected calcite-autocomplete-item will remove the most recently added from the component.
SpaceIf the component is not open, opens the component.
Arrow upIf 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 downIf 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.
EnterIf the component is open and a calcite-autocomplete-item is active, will select the item.
EscIf the component is open, closes the component.
TabMoves focus in and out of the component. If the component is not open and calcite-autocomplete-items are present, the component will open. If the component is open, the component will close.
Tab and ShiftMoves 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.
HomeMoves 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.
EndMoves 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

PropertyAttributeDescriptionTypeDefault
alignmentalignmentSpecifies the text alignment of the component's value."end" | "start""start"
autocompleteSpecifies the type of content to autocomplete, for use in forms. Read the native attribute's documentation on MDN for more info.AutoFill
disableddisabledWhen true, interaction is prevented and the component is displayed with lower opacity.booleanfalse
flipPlacementsSpecifies the component's fallback placement when it's initial or specified placement has insufficient space available.Array<"top" | "bottom" | "right" | "left" | "top-start" | "top-end" | "bottom-start" | "bottom-end" | "right-start" | "right-end" | "left-start" | "left-end" | "leading-start" | "leading" | "leading-end" | "trailing-end" | "trailing" | "trailing-start">
formformThe id of the form that will be associated with the component. When not set, the component will be associated with its ancestor form element, if any.string
iconiconWhen true, shows a default recommended icon. Alternatively, pass a Calcite UI Icon name to display a specific icon.boolean | string
iconFlipRtlicon-flip-rtlWhen true, the icon will be flipped when the element direction is right-to-left ("rtl").booleanfalse
inputValueinput-valueThe component's input value.string
labellabelAccessible name for the component.string
loadingloadingWhen true, a busy indicator is displayed.booleanfalse
maxLengthmax-lengthWhen the component resides in a form, specifies the maximum length of text for the component's value.number
messageOverridesUse this property to override individual strings used by the component.{ clear?: string; loading?: string; }
minLengthmin-lengthWhen the component resides in a form, specifies the minimum length of text for the component's value.number
namenameSpecifies the name of the component. Required to pass the component's value on form submission.string
openopenWhen true, displays and positions the component.booleanfalse
overlayPositioningoverlay-positioningDetermines the type of positioning to use for the overlaid content. Using "absolute" will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout. "fixed" should be used to escape an overflowing parent container, or when the reference element's position CSS property is "fixed"."absolute" | "fixed""absolute"
patternpatternWhen 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
placeholderplaceholderSpecifies placeholder text for the component.string
placementplacementDetermines where the component will be positioned relative to the container element."bottom" | "bottom-end" | "bottom-start" | "top" | "top-end" | "top-start""bottom-start"
prefixTextprefix-textAdds text to the start of the component.string
readOnlyread-onlyWhen true, the component's value can be read, but cannot be modified.booleanfalse
requiredrequiredWhen true and the component resides in a form, the component must have a value in order for the form to submit.booleanfalse
scalescaleSpecifies the size of the component."l" | "m" | "s""m"
statusstatusSpecifies the status of the input field, which determines message and icons."idle" | "invalid" | "valid""idle"
suffixTextsuffix-textAdds text to the end of the component.string
validationIconvalidation-iconSpecifies the validation icon to display under the component.boolean | string
validationMessagevalidation-messageSpecifies the validation message to display under the component.string
validityread-onlyThe current validation state of the component.{ valid: boolean; badInput: boolean; customError: boolean; patternMismatch: boolean; rangeOverflow: boolean; rangeUnderflow: boolean; stepMismatch: boolean; tooLong: boolean; tooShort: boolean; typeMismatch: boolean; valueMissing: boolean; }
valuevalueThe component's value.string""

Slots

NameDescription
default (unnamed)A slot for adding calcite-autocomplete-item elements.
content-bottomA slot for adding content below calcite-autocomplete-item elements.
content-topA slot for adding content above calcite-autocomplete-item elements.

Styles

NameDescription
--calcite-autocomplete-background-colorSpecifies the background color of the component.
--calcite-autocomplete-corner-radiusSpecifies the component's corner radius.
--calcite-autocomplete-text-colorSpecifies the text color of the component.
--calcite-autocomplete-input-prefix-sizeSpecifies the Input's prefix width, when present.
--calcite-autocomplete-input-suffix-sizeSpecifies the Input's suffix width, when present.
--calcite-autocomplete-input-background-colorSpecifies the background color of the Input.
--calcite-autocomplete-input-border-colorSpecifies the border color of the Input.
--calcite-autocomplete-input-corner-radiusSpecifies the corner radius of the Input.
--calcite-autocomplete-input-shadowSpecifies the shadow of the Input.
--calcite-autocomplete-input-icon-colorSpecifies the icon color of the Input.
--calcite-autocomplete-input-text-colorSpecifies the text color of the Input.
--calcite-autocomplete-input-placeholder-text-colorSpecifies the color of placeholder text in the Input.
--calcite-autocomplete-input-actions-background-colorSpecifies the background color of Input's clearable element.
--calcite-autocomplete-input-actions-background-color-hoverSpecifies the background color of Input's clearable element when hovered.
--calcite-autocomplete-input-actions-background-color-pressSpecifies the background color of Input's clearable element when pressed.
--calcite-autocomplete-input-actions-icon-colorSpecifies the icon color of Input's clearable element.
--calcite-autocomplete-input-actions-icon-color-hoverSpecifies the icon color of Input's clearable element when hovered.
--calcite-autocomplete-input-actions-icon-color-pressSpecifies the icon color of Input's clearable element when pressed.
--calcite-autocomplete-input-loading-background-colorSpecifies the background color of the Input's loading element, when present.
--calcite-autocomplete-input-loading-fill-colorSpecifies the fill color of the Input's loading element, when present.
--calcite-autocomplete-input-prefix-background-colorSpecifies the background color of the Input's prefix, when present.
--calcite-autocomplete-input-prefix-text-colorSpecifies the text color of the Input's prefix, when present.
--calcite-autocomplete-input-suffix-background-colorSpecifies the background color of the Input's suffix, when present.
--calcite-autocomplete-input-suffix-text-colorSpecifies the text color of the Input's suffix, when present.

Events

NameDescriptionBehavior
calciteAutocompleteBeforeCloseFires when the component is requested to be closed and before the closing transition begins.bubblescomposed
calciteAutocompleteBeforeOpenFires when the component is added to the DOM but not rendered, and before the opening transition begins.bubblescomposed
calciteAutocompleteChangeFires each time a new value is typed and committed.bubblescomposed
calciteAutocompleteCloseFires when the component is closed and animation is complete.bubblescomposed
calciteAutocompleteOpenFires when the component is open and animation is complete.bubblescomposed
calciteAutocompleteTextChangeFires each time a new inputValue is typed and committed.bubblescomposed
calciteAutocompleteTextInputFires each time a new inputValue is typed.bubblescomposed

Methods

NameDescriptionSignature
componentOnReadyCreate a promise that resolves once component is fully loaded.componentOnReady(): Promise<void>
repositionUpdates the position of the component.reposition(delayed?: boolean): Promise<void>
scrollContentToScrolls the component's content to a specified set of coordinates.scrollContentTo(options?: ScrollToOptions): Promise<void>
selectTextSelects the text of the component's value.selectText(): Promise<void>
setFocusSets focus on the component's first focusable element.setFocus(): Promise<void>

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.

You can no longer sign into this site. Go to your ArcGIS portal or the ArcGIS Location Platform dashboard to perform management tasks.

Your ArcGIS portal

Create, manage, and access API keys and OAuth 2.0 developer credentials, hosted layers, and data services.

Your ArcGIS Location Platform dashboard

Manage billing, monitor service usage, and access additional resources.

Learn more about these changes in the What's new in Esri Developers June 2024 blog post.

Close