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
<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>
Best practices
While visually similar to the Combobox, the Autocomplete component has distinct capabilities and intended use cases.
Comparison
Recommendations
Accessibility
Keyboard navigation
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. | "end" | "start" | "start" |
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 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"> | ||
form | form | The 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 | |
icon | icon | When true , shows a default recommended icon. Alternatively, pass a Calcite UI Icon name to display a specific icon. | boolean | string | |
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 | The component's input value. | string | |
label | label | Accessible name for the component. | 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 | Use this property to override individual strings used by the component. | {
clear?: string;
loading?: string;
} | ||
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 | Determines 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" |
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. | "bottom" | "bottom-end" | "bottom-start" | "top" | "top-end" | "top-start" | "bottom-start" |
prefixText | prefix-text | Adds text to the start of the component. | 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. | "l" | "m" | "s" | "m" |
status | status | Specifies the status of the input field, which determines message and icons. | "idle" | "invalid" | "valid" | "idle" |
suffixText | suffix-text | Adds text to the end of the component. | string | |
validationIcon | validation-icon | Specifies the validation icon to display under the component. | boolean | string | |
validationMessage | validation-message | Specifies the validation message to display under the component. | string | |
validity | The 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;
} | ||
value | value | The component's value. | 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. |
Styles
Name | Description |
---|---|
--calcite-autocomplete-background-color | Specifies the background color of the component. |
--calcite-autocomplete-corner-radius | Specifies the component's corner radius. |
--calcite-autocomplete-text-color | Specifies the text color of the component. |
--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 Input. |
--calcite-autocomplete-input-border-color | Specifies the border color of the Input. |
--calcite-autocomplete-input-corner-radius | Specifies the corner radius of the Input. |
--calcite-autocomplete-input-shadow | Specifies the shadow of the Input. |
--calcite-autocomplete-input-icon-color | Specifies the icon color of the Input. |
--calcite-autocomplete-input-text-color | Specifies the text color of the Input. |
--calcite-autocomplete-input-placeholder-text-color | Specifies the color of placeholder text in the Input. |
--calcite-autocomplete-input-actions-background-color | Specifies the background color of Input's clearable element. |
--calcite-autocomplete-input-actions-background-color-hover | Specifies the background color of Input's clearable element when hovered. |
--calcite-autocomplete-input-actions-background-color-press | Specifies the background color of Input's clearable element when pressed. |
--calcite-autocomplete-input-actions-icon-color | Specifies the icon color of Input's clearable element. |
--calcite-autocomplete-input-actions-icon-color-hover | Specifies the icon color of Input's clearable element when hovered. |
--calcite-autocomplete-input-actions-icon-color-press | Specifies the icon color of 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-background-color | Specifies the background color of the Input's prefix, when present. |
--calcite-autocomplete-input-prefix-text-color | Specifies the text color of the Input's prefix, when present. |
--calcite-autocomplete-input-suffix-background-color | Specifies the background color of the Input's suffix, 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. | |
calciteAutocompleteBeforeOpen | Fires when the component is added to the DOM but not rendered, and before the opening transition begins. | |
calciteAutocompleteChange | Fires each time a new value is typed and committed. | |
calciteAutocompleteClose | Fires when the component is closed and animation is complete. | |
calciteAutocompleteOpen | Fires when the component is open and animation is complete. | |
calciteAutocompleteTextChange | Fires each time a new inputValue is typed and committed. | |
calciteAutocompleteTextInput | Fires each time a new inputValue is typed. |
Methods
Name | Description | Signature |
---|---|---|
componentOnReady | Create a promise that resolves once component is fully loaded. | componentOnReady(): Promise<void> |
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(): Promise<void> |