Origami Frontend Components & Services

Readme: o-autocomplete

An Origami component for autocomplete inputs. This is built on top of the excellent accessible autocomplete component by AlphaGov.

Usage

Check out how to include Origami components in your project to get started with o-autocomplete.

Markup

For a static set of suggestions

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>

For a dynamic set of suggestions

To provide a dynamic set of suggestions, you will need to 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>

Use with o-forms

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:

<label class="o-forms-field" >
    <span class="o-forms-title">
        <span class="o-forms-title__main">Select your country</span>
    </span>
    <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>
</label>

Sass

Use @include oAutocomplete() to include styles for all o-autocomplete features.

@import "@financial-times/o-autocomplete/main";

@include oAutocomplete();

JavaScript

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);

dynamic suggestions function

Example

import oAutocomplete from 'o-autocomplete';

/**
 * @callback PopulateOptions
 * @param {Array<*>} options - The options which match the rext 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:

(query, suggestionsCallback) ⇒ void

Param Type Description
query string Text which was typed into the text input
suggestionsCallback suggestionsCallback Function to call when ready to update the suggestions menu

suggestionsCallback : function

Properties

Name Type Description
options Array.&lt;*&gt; The options which match the entered query

mapOptionToSuggestedValue

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.

Example

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,
});

MapOptionToSuggestedValue ⇒ string

Returns: string - The string to display as the suggestions for this option

Param Type Description
option \* The option to transform into a suggestion string

onConfirm

This function is called when the user selects an option and is called with the option the user selected.

Example

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,
});

onConfirm ⇒ void

Param Type Description
option \* The option the user selected

Keyboard Support

When focus is within the text input

Key Function
Down Arrow If the suggestions menu is displayed, moves focus to the first suggested value in the suggestions menu.
Enter If the suggestions menu is displayed, does nothing.
Escape If the suggestions menu is displayed, closes it.

When focus is within the suggestions menu

Key Function
Enter
  • Sets the text input value to the content of the focused option in the suggestions menu.
  • Closes the suggestions menu.
  • Sets focus on the text input.
Tab
  • Sets the text input value to the content of the focused option in the suggestions menu.
  • Closes the suggestions menu.
  • Sets focus on the clear button.
Space
  • Sets the text input value to the content of the focused option in the suggestions menu.
  • Closes the suggestions menu.
  • Sets focus on the text input.
Up Arrow If focus is on the first option, returns focus to the text input. Otherwise, moves focus to and selects the previous option in the suggestions menu.
Down Arrow If focus is on the last option, does nothing. Otherwise, moves focus to and selects the next option in the suggestions menu.
Backspace Returns focus to the text input and deletes the character prior to the cursor
Printable Characters
  • Moves focus to the text input.
  • Types the characters into the text input.

When focus is within the clear button

Key Function
Enter
  • Moves focus to the text input.
  • Removes all the characters within the text input.
Space
  • Moves focus to the text input.
  • Removes all the characters within the text input.

Migration

State Major Version Last Minor Release Migration guide
✨ active 1 1.0 N/A

Contact

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.

Licence

This software is published by the Financial Times under the MIT licence.

Status
active
Switch component view

GitHub: o-autocomplete@1.6.1

Install o-autocomplete

If using the Build Service, add o-autocomplete@^1.6.1 to your script and link tags.

If using the npm package manager for a Manual Build, run npm install --save-peer "@financial-times/o-autocomplete@^1.6.1".

Help & Support

o-autocomplete is maintained directly by the Origami team. If you have any questions about o-autocomplete or Origami in general, we are happy to help. 😊

Slack: #origami-support
Email: origami.support@ft.com

Feedback / Issues

To report a bug or request features please create an issue on Github. For support or general feedback please get in touch 😊

Slack: #origami-support
Email: origami.support@ft.com