An Origami component for autocomplete inputs. This is built on top of the excellent accessible autocomplete component by AlphaGov.
Check out how to include Origami components in your project to get started with o-autocomplete.
To provide a static set of suggestions, we recommend using a select element. o-autocomplete will progressively enhance the select element, using the provided option elements as the source for the suggestions.
<label for="my-autocomplete">Select your country</label>
<span data-o-component="o-autocomplete" class="o-autocomplete">
<select id="my-autocomplete">
<option value="fr">France</option>
<option value="de">Germany</option>
<option value="gb">United Kingdom</option>
</select>
</span>To provide a dynamic set of suggestions, provide a javascript function or name of a javascript function on the window object which follows the dynamic-suggestions-function API.
The input element requires an id attribute, this is used within the component to implement the accessibility features.
<span data-o-component="o-autocomplete" class="o-autocomplete">
<input id="my-autocomplete" type="text" >
</span>To have styling for labels, you will need to use o-forms as part of the autocomplete implementation.
Below is an example of how to combine o-forms and o-autocomplete components together. Note the label and select element are connected using for and id attributes.
<span class="o-forms-field" >
<label for="my-autocomplete" class="o-forms-title">
<span class="o-forms-title__main">Select your country</span>
</label>
<span class="o-forms-input o-forms-input--select">
<span data-o-component="o-autocomplete" class="o-autocomplete">
<select id="my-autocomplete">
<option value=""></option>
<option>Afghanistan</option>
</select>
</span>
</span>
</span>Use @include oAutocomplete() to include styles for all o-autocomplete features.
@import "@financial-times/o-autocomplete/main";
@include oAutocomplete();JavaScript is initialised automatically for Origami Build Service users.
If your project is using a manual build process, initialise o-autocomplete manually.
For example call the init method to initialise all o-autocomplete instances in the document:
import oAutocomplete from 'o-autocomplete';
oAutocomplete.init();Or pass an element to initialise a specific o-autocomplete instance:
import oAutocomplete from 'o-autocomplete';
const oAutocompleteElement = document.getElementById('#my-o-autocomplete-element');
new oAutocomplete(oAutocompleteElement);import oAutocomplete from 'o-autocomplete';
/**
* @callback PopulateOptions
* @param {Array<*>} options - The options which match the text which was typed into the autocomplete by the user
* @returns {void}
*/
/**
* @param {string} query - Text which was typed into the autocomplete by the user
* @param {PopulateOptions} populateOptions - Function to call when ready to update the suggestions dropdown
* @returns {void}
*/
async function customSuggestions(query, populateOptions) {
const suggestions = await getSuggestions(query);
populateOptions(suggestions);
}
const oAutocompleteElement = document.getElementById('#my-o-autocomplete-element');
new oAutocomplete(oAutocompleteElement, {
source: customSuggestions
});If wanting to supply dynamic suggestions, you will need to provide a function which implements the following API:
voidfunctionProperties
This function is used to convert the options returned from the source function into strings for the suggestions menu.
If the source function is returning an array of strings which are already suitable to be displayed in within the suggestions menu, then there is no need to define a mapOptionToSuggestedValue function.
The most common scenario which requires having to define a mapOptionToSuggestedValue function is when the source function is returning an array of objects, where one of the properties in the object should be used as the suggestion.
import oAutocomplete from 'o-autocomplete';
async function customSuggestions(query, populateOptions) {
const suggestions = await getSuggestions(query);
populateOptions(suggestions);
}
/**
* @param {{"suggestionText": string}} option - The option to transform into a suggestion string
* @returns {string} The string to display as the suggestions for this option
*/
function mapOptionToSuggestedValue(option) {
return option.suggestionText;
}
const oAutocompleteElement = document.getElementById('#my-o-autocomplete-element');
new oAutocomplete(oAutocompleteElement, {
mapOptionToSuggestedValue,
source: customSuggestions,
});stringReturns: string - The string to display as the suggestions for this option
This function is called when the user selects an option and is called with the option the user selected.
import oAutocomplete from 'o-autocomplete';
async function customSuggestions(query, populateOptions) {
const suggestions = await getSuggestions(query);
populateOptions(suggestions);
}
/**
* @param {{"suggestionText": string}} option - The option to transform into a suggestion string
* @returns {string} The string to display as the suggestions for this option
*/
function mapOptionToSuggestedValue(option) {
return option.suggestionText;
}
/**
* @param {{"suggestionText": string}} option - The option the user selected
*/
function onConfirm(option) {
console.log('You selected option: ', option);
}
const oAutocompleteElement = document.getElementById('#my-o-autocomplete-element');
new oAutocomplete(oAutocompleteElement, {
onConfirm
mapOptionToSuggestedValue,
source: customSuggestions,
});voiddefaultValue (default: '')Type: string
If setting a default input value for a dynamic set of suggestions set the defaultValue option.
When progressively enhancing a static set of suggestions set a default value using HTML, by providing an appropriate option element.
If you have any questions or comments about this component, or need help using it, please either raise an issue, visit ##origami-support or email origami.support@ft.com.
This software is published by the Financial Times under the MIT licence.