Autocomplete
Autocomplete allows users to search through a list of options and select a value. It supports keyboard navigation, custom filtering, and rich options with labels and descriptions.
Ads by Tryg Careers
Installation
npm i @tryg/react-ui-libraryUsage
The AnchorAutocomplete component allows users to search through a list of options and select a value. It supports keyboard navigation, custom filtering, and rich options with labels and descriptions.
<AnchorAutocomplete
label="Search Countries"
options={['United States', 'United Kingdom', 'Canada', 'Australia', 'Germany']}
placeholder="Start typing to search..."
/>Rich Options
Options can be passed as an array of OptionValue objects with value, label, and optional description properties.
<AnchorAutocomplete
label="Select Country"
options={[
{ value: 'us', label: 'United States' },
{ value: 'uk', label: 'United Kingdom' },
{ value: 'ca', label: 'Canada' },
]}
placeholder="Search by country name..."
/>Options with Descriptions
Options can include a description field that provides additional context in the dropdown.
<AnchorAutocomplete
label="Select Region"
options={[
{ value: 'na', label: 'North America', description: 'United States, Canada, Mexico' },
{ value: 'eu', label: 'Europe', description: 'Western and Eastern European countries' },
{ value: 'asia', label: 'Asia', description: 'East Asian and Southeast Asian countries' },
]}
placeholder="Search regions..."
/>Disabled
<AnchorAutocomplete
label="Search Countries"
options={['United States', 'United Kingdom', 'Canada']}
placeholder="Cannot interact with this field"
disabled
/>Read Only
<AnchorAutocomplete
label="Search Countries"
options={['United States', 'United Kingdom', 'Canada']}
placeholder="This field is read-only"
readonly
/>Required
If you pass the required prop, the field will be required for form validation.
<AnchorAutocomplete
label="Search Countries"
options={['United States', 'United Kingdom', 'Canada']}
required
/>Help Text
You can add helpful text by passing the helpText prop.
<AnchorAutocomplete
label="Search Countries"
options={['United States', 'United Kingdom', 'Canada']}
placeholder="Search countries..."
helpText="Enter a country name to see suggestions"
/>Error Message
When showError is true (default), typing a value not selected from the dropdown will display an error message on blur. Customize it with errorText.
<AnchorAutocomplete
label="Search Countries"
options={['United States', 'United Kingdom', 'Canada']}
errorText="Please select a valid country"
/>Filter Options
Filter Condition
Control how the default filter matches options using the filterCondition prop. The default is contains.
<AnchorAutocomplete
label="Search Countries"
options={['United States', 'United Kingdom', 'Canada', 'Australia', 'Germany']}
filterCondition="startsWith"
helpText="Only shows options that start with your input"
/>Available filter conditions:
contains— Shows options that contain the input text anywhere (default)startsWith— Shows options that start with the input textendsWith— Shows options that end with the input text
Custom Filter Function
For full control over filtering, pass a custom filter function via the filterFn prop.
const customFilter: (options: OptionValue[], input: string, condition?: string) => OptionValue[] =
(options, input) => {
const trimmed = input?.toLowerCase().trim();
if (!trimmed) return options;
return options.filter(opt =>
(opt.label || opt.value).toLowerCase().startsWith(trimmed)
);
};
<AnchorAutocomplete
label="Search Countries"
options={['United States', 'United Kingdom', 'Canada']}
filterFn={customFilter}
/>Expand Behavior
Expand on Click
The dropdown expands when the user clicks the input (default behavior).
<AnchorAutocomplete
label="Search Countries"
options={['United States', 'United Kingdom', 'Canada']}
expandOn="click"
helpText="Dropdown expands when you click the input"
/>Expand on Character Limit
The dropdown expands only after the user types a minimum number of characters.
<AnchorAutocomplete
label="Search Countries"
options={['United States', 'United Kingdom', 'Canada']}
expandOn="charLimit"
charLimit={3}
helpText="Dropdown expands after typing 3 characters"
/>Backend Filtering
When filtering on your backend (e.g., querying an API for each keystroke), listen to the inputchange event and update the options prop with the server response.
import { useEffect, useRef, useState, useCallback } from 'react';
import { AnchorAutocomplete } from '@tryg/react-ui-library';
function SearchAutocomplete() {
const autocompleteRef = useRef<HTMLAnchorAutocompleteElement>(null);
const [options, setOptions] = useState([]);
const [loading, setLoading] = useState(false);
const abortControllerRef = useRef<AbortController | null>(null);
const handleInputChange = useCallback(async (e: CustomEvent) => {
const searchTerm = e.detail.value;
// Abort previous in-flight request
if (abortControllerRef.current) abortControllerRef.current.abort();
abortControllerRef.current = new AbortController();
setLoading(true);
try {
const response = await fetch(`/api/countries?q=${encodeURIComponent(searchTerm)}`, {
signal: abortControllerRef.current.signal
});
const data = await response.json();
setLoading(false);
setOptions(data.map(c => ({ value: c.id, label: c.name })));
} catch (err) {
if (err.name !== 'AbortError') {
setLoading(false);
}
}
}, []);
useEffect(() => {
const el = autocompleteRef.current;
if (!el) return;
el.addEventListener('inputchange', handleInputChange);
return () => el.removeEventListener('inputchange', handleInputChange);
}, [handleInputChange]);
return (
<AnchorAutocomplete
ref={autocompleteRef}
label="Search Countries"
options={options}
loading={loading}
loadText="Searching countries..."
placeholder="Search..."
/>
);
}Loading State
Set loading to display a loading indicator while options are being fetched asynchronously.
<AnchorAutocomplete
label="Search Countries"
options={[]}
loading
loadText="Searching countries..."
/>Search Icon
Show a search icon in the input using the showIcon prop. The icon is visible when the dropdown is collapsed and no option is selected.
<AnchorAutocomplete
label="Search Countries"
options={['United States', 'United Kingdom', 'Canada']}
showIcon
helpText="Search icon hides when dropdown is open or option is selected"
/>Events
The Autocomplete component emits several custom events that can be listened to for reactive behavior.
import { useEffect, useRef, useCallback } from 'react';
import { AnchorAutocomplete } from '@tryg/react-ui-library';
function AutocompleteWithEvents() {
const ref = useRef<HTMLAnchorAutocompleteElement>(null);
useEffect(() => {
const el = ref.current;
if (!el) return;
const handlers = {
selectevent: (e: CustomEvent) => console.log('Selected:', e.detail),
inputchange: (e: CustomEvent) => console.log('Input changed:', e.detail),
expand: (e: CustomEvent) => console.log('Dropdown expanded:', e.detail),
collapse: (e: CustomEvent) => console.log('Dropdown collapsed:', e.detail),
highlight: (e: CustomEvent) => console.log('Option highlighted:', e.detail),
focusevent: (e: CustomEvent) => console.log('Input focused:', e.detail),
blurevent: (e: CustomEvent) => console.log('Input blurred:', e.detail),
};
Object.entries(handlers).forEach(([event, handler]) =>
el.addEventListener(event, handler)
);
return () => {
Object.entries(handlers).forEach(([event, handler]) =>
el.removeEventListener(event, handler)
);
};
}, []);
return (
<AnchorAutocomplete
ref={ref}
label="Search Countries"
options={['United States', 'United Kingdom', 'Canada', 'Australia', 'Germany']}
placeholder="Interact to see events in console"
/>
);
}| Event | Detail Type |
|---|---|
selectevent | { value: string, label: string } |
inputchange | { value: string } |
expand | { expanded: true, searchTerm: string } |
collapse | { expanded: false, selected: boolean } |
highlight | { index: number, value: string, label: string } |
focusevent | { value: string } |
blurevent | { value: string, selected: boolean, error: boolean } |
Accessibility
The Autocomplete component implements the ARIA combobox pattern:
- The input uses
role="combobox"witharia-expanded,aria-controls, andaria-activedescendant - The dropdown list uses
role="listbox" - Options use
role="option"witharia-selectedstate - Full keyboard navigation is supported:
- Arrow Down — Open dropdown / move focus to next option
- Arrow Up — Move focus to previous option
- Enter / Space — Select the currently focused option
- Escape — Close the dropdown
Accessibility Considerations
- Avoid very long option names to facilitate understanding and perception.
- Don't use the same word or phrase at the beginning of a set of options.
- If the autocomplete is a required field, include the
requiredprop and indicate that it is a required field.
Guidelines
Do use
- Autocomplete in full pages, forms, modals, and side panels
- Autocomplete to select values from a large dataset
Don't use
- Use a select or radio group instead when there are only a limited number of options to choose from
API
anchor-typeahead
WORK IN PROGRESS: This component is new
How to use the typeahead component
Basic typeahead
<anchor-typeahead options='["foo","bar","foobar"]' language="NO" texts='{"noResult":"The search yeilded no results"}'></anchor-typeahead>Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
charLimit | char-limit | Character limit to expand on for Autocomplete | number | 1 |
disabled | disabled | Disable flag for Autocomplete | boolean | false |
errTextPlacement | err-text-placement | This prop decides if the messages should render between the label of an input and the input field, or below the input field. | "below" | "inside" | 'inside' |
errorText | error-text | Error text for Autocomplete | string | "default error text" |
expandOn | expand-on | Expand condition for Autocomplete | "charLimit" | "click" | 'click' |
filterCondition | filter-condition | Filter condition to be used with default filter function for Autocomplete | "contains" | "endsWith" | "startsWith" | 'contains' |
filterFn | -- | Custom Filter Function for Autocomplete | (options: OptionValue[], input: string, condition?: string) => OptionValue[] | filterOptions |
helpText | help-text | Helpful Text for Autocomplete | string | undefined |
inputValue | input-value | Value inputed | string | undefined |
label | label | Label for Autocomplete | string | undefined |
loadText | load-text | Text to show when loading is true | string | "Searching..." |
loading | loading | To set a loading state while options are recieved | boolean | false |
noOptionsErrorText | no-options-error-text | No options text for Autocomplete | string | "No Options found" |
options | options | Options for Autocomplete | (string | OptionValue)[] | string | undefined |
placeholder | placeholder | Placeholder Text for Autocomplete | string | undefined |
readonly | readonly | ReadOnly flag for Autocomplete | boolean | false |
required | required | Mark the field as required for form validation. | boolean | false |
showError | show-error | Show error on not selecting from dropdown | boolean | true |
showIcon | show-icon | Show search icon for Autocomplete | boolean | false |
uuid | uuid | The unique id of the input field | string | uuidv4() |
Events
| Event | Description | Type |
|---|---|---|
blurevent | Event emitted when the input loses focus | CustomEvent<AutocompleteBlurEventDetail> |
collapse | Event emitted when the dropdown collapses | CustomEvent<AutocompleteCollapseEventDetail> |
expand | Event emitted when the dropdown expands | CustomEvent<AutocompleteExpandEventDetail> |
focusevent | Event emitted when the input receives focus | CustomEvent<AutocompleteFocusEventDetail> |
highlight | Event emitted for a highlighted selection when a user uses arrow keys for navigating options | CustomEvent<AutocompleteHighlightEventDetail> |
inputchange | Event emitted when input field is changed | CustomEvent<AutocompleteInputEventDetail> |
selectevent | Event emitted when a valid option has been selected | CustomEvent<AutocompleteSelectEventDetail> |
Dependencies
Depends on
Graph
graph TD;
anchor-autocomplete --> anchor-input
anchor-autocomplete --> anchor-option
anchor-input --> anchor-form-field
anchor-input --> anchor-icon
anchor-input --> anchor-tooltip
anchor-form-field --> anchor-icon
anchor-option --> anchor-icon
style anchor-autocomplete fill:#f9f,stroke:#333,stroke-width:4pxBuilt with StencilJS