Skip to content

Autocomplete13.10.5

Autocompletes allow users to enter any combination of letters, numbers, or symbols of their choosing (unless otherwise restricted), and receive one or more suggested matches in a list below the input.


$ npm i @if-design-system/autocomplete@13.10.5

Tips: start searching: "how do i.."
  1. how do I convert to pdf
  2. how do I convert to muslim
  3. how do I convert to judaism
  4. how do I convert to christianity
  5. how do I convert to catholic
  6. how do I convert to mp3
Edit this section

Overview

Unlike a Select (single- or multi-) that lets you select options from an options menu, the Autocomplete component has other behavior beyond choosing an option as the value for a setting, such as linking to other content.

Other relevant components:

Edit this section

Variations

Type Purpose
Autocomplete string This version is used when you want users to select from string matches and items.
Autocomplete tags This version is used when you want users to selected predefined tags, like filters.
Edit this section

Usage

Principles

  • User can type, and if suggestions is found, they appear with the matched string highlighted
  • User can navigate through the suggestions with ↑ UP and ↓ DOWN arrow keys
Edit this section

Behaviours

The default behaviour of the autocomplete input element is like any other input element. They key difference is a list of suggestions popping up when typing.

Interactions

No results

When no results is found, a "No results" message is displayed

Tips: start searching: "how do i.."
  1. No results
No results

Loading state

If autocomplete options are likely to take longer than 1 second to show for the majority of users, display a loading indicator.

Tips: start searching: "Bar"
Loading
<div class="if input-wrapper autocomplete [tags] is-loading"></div>

Focus

Tips: start searching: "Bar"
  1. Barks väg 15, 106 80 Solna, Sverige
  2. Barks väg 16, 106 80 Solna, Sverige
Keyboard focus

The autocomplete suggestion element follows the same principles for default focus styling when keyboard is used:

3px outline with color BL 1, BLUE Complement, a direct complement color of BL 1, BLUE.

Tips: start searching: "Bar"
  1. Barks väg 15, 106 80 Solna, Sverige
  2. Barks väg 16, 106 80 Solna, Sverige
Mouse focus

No general mouse focus, but when an item is hovered or selected, it receives fill color BE 3, LIGHT BEIGE

Edit this section

Autocomplete string

The autocomplete string version is used when you want users to select from string matches and items.

Tips: start typing: "how do i.."
  1. how do I convert to pdf
  2. how do I convert to muslim
  3. how do I convert to judaism
  4. how do I convert to christianity
  5. how do I convert to catholic
  6. how do I convert to mp3
Mobile

For example search, with the Search Field component:

Implementation

Here is the default autocomplete string html code. Code for the suggestion elements follows below.

<form class="if" action="none" onsubmit="javascript: return false;">
  <div class="if input-wrapper autocomplete">
    <input
      type="search"
      class="if input-field"
      name="search"
      placeholder="Enter your search"
      aria-expanded="false"
      aria-owns="autocomplete-string-index-1"
      aria-autocomplete="list"
      autocomplete="off"
      role="combobox"
    />
    <label for="search" class="if">
      Search
    </label>
    <div class="if input-help">
      Tips: start typing: "how do i.."
    </div>
    <ol id="autocomplete-suggestions-1" role="listbox" class="if suggestions"></ol>
  </div>
</form>

Suggestion element:

<li
  data-rel="how do I convert to pdf"
  role="option"
  aria-setsize="6"
  aria-posinset="1"
  tabindex="-1"
  aria-selected="false|true"
  class="if [is-selected]"
>
  <span class="if"><mark class="if">how do I convert to </mark>pdf</span>
</li>
Edit this section

Autocomplete tags

    Create tags by typing and use comma , or Enter to add them
    1. immovableness
    2. imbrium
    Create tags by typing and use comma , or Enter to add them

    Usage

    Principles

    • Tags are created either with comma separated words or space separated phrases
    • If applicable a predefined set of tags can appear as autocomplete with suggestions
    • User can navigate through the suggestions with ↑ UP and ↓ DOWN arrow keys
    • User can use backspace to remove tags
    • User can click the cross in the tag to remove the tag
    • Every tag removed is put back into the array of suggestions, for historical usage

    Anatomy

    The autocomplete suggestions follow the same principles as a basic autocomplete.

    1. immovableness
    2. imbrium
    Create tags by typing and use comma , or Enter to add them

    Implementation

    The html implementation for suggestions are the same as for string. They key difference is in the input layout:

    2,14c2,5
    -   <div class="if input-wrapper autocomplete">
    -     <input
    -       type="text"
    -       class="if input-field"
    -       name="autocomplete-1"
    -       aria-expanded="false"
    -       aria-owns="some-id"
    -       aria-autocomplete="list"
    -       autocomplete="off"
    -       role="combobox"
    -     />
    -     <label for="autocomplete-1" class="if">
    -       Search
    ---
    +   <div class="if input-wrapper autocomplete tags">
    +     <input type="text" class="if input-field tag-holder" value="Orwell, 1984" name="tags" />
    +     <label for="tags" class="if">
    +       Choose tags
    16c7,24
    -     <div class="if input-help">
    ---
    +     <div class="if autocomplete-tags-input-holder">
    +       <ol id="some-id" role="listbox" class="if suggestions"></ol>
    +       <button type="button" data-rel="Orwell" aria-label="Remove Orwell" class="if tag input">
    +         Orwell
    +       </button>
    +       <button type="button" data-rel="1984" aria-label="Remove 1984" class="if tag input">
    +         1984
    +       </button>
    +       <input
    +         type="text"
    +         class="if input-field"
    +         name="autocomplete-1"
    +         aria-expanded="false"
    +         aria-owns="some-id"
    +         aria-autocomplete="list"
    +         autocomplete="off"
    +         role="combobox"
    +       />
    18c26,27
    -     <ol id="some-id" role="listbox" class="if suggestions"></ol>
    ---
    +     <span class="if input-help">
    +     </span>
    <form class="if" action="none" onsubmit="javascript: return false;">
      <div class="if input-wrapper autocomplete tags">
        <input type="text" class="if input-field tag-holder" value="Orwell, 1984" name="tags" />
        <label for="tags" class="if">
          Choose tags
        </label>
        <div class="if autocomplete-tags-input-holder">
          <ol id="some-id" role="listbox" class="if suggestions"></ol>
          <button type="button" data-rel="Orwell" aria-label="Remove Orwell" class="if tag input">
            Orwell
          </button>
          <button type="button" data-rel="1984" aria-label="Remove 1984" class="if tag input">
            1984
          </button>
          <input
            type="text"
            class="if input-field"
            name="autocomplete-1"
            aria-expanded="false"
            aria-owns="some-id"
            aria-autocomplete="list"
            autocomplete="off"
            role="combobox"
          />
        </div>
        <span class="if input-help"> </span>
      </div>
    </form>
    Key changes
    1. The main input field used for forms is hidden and is populated with the tags added or pre-added
    2. This element is styled like an input field
    3. Added or pre-added tags are here
    Edit this section

    Accessibility

    Keyboard navigation

    • When tabbing forward or backward through the page, let the autocomplete text input take keyboard focus with the tab key
    • Let people navigate through the list of autocomplete options using the up and down arrow keys
    • Let people select the option that has focus using the Enter key

    Announcements

    Let people using screen readers know when new options are presented while typing. This requires testing to avoid excessively noisy announcements.

    If the Autocomplete component causes a change to content on the page, use ARIA live regions to inform screen reader users of what's changed.

    Edit this section

    Anatomy

    • Suggestions: the bit that drops down from an input field to show Autocomplete suggestions.
    • Autocomplete suggestion item: the suggestions menu that lets you choose a suggestion.
    • Each suggestion may be presented as plain text or with icons.
    Tips: start searching: "how do i.."
    1. how do I convert to pdf
    2. how do I convert to muslim
    3. how do I convert to judaism
    4. how do I convert to christianity
    5. how do I convert to catholic
    6. how do I convert to mp3
    1. Suggestions
    2. Selected/Hovered
    3. Emphasized matched string
    Edit this section

    Specs

    Tips: start searching: "how do i.."
    1. how do I convert to pdf
    2. how do I convert to muslim
    3. how do I convert to judaism
    4. how do I convert to christianity
    5. how do I convert to catholic
    6. how do I convert to mp3
    Edit this section

    Code

    JavaScript Library

    JavaScript support library for the Autocomplete Component.

    This component is compatible with CommonJS, ESM (ES6 module) and UMD. See documentation examples below.

    Install

    $ npm install @if-design-system/autocomplete-js

    Or for Yarn:

    $ yarn add @if-design-system/autocomplete-js

    Features

    • Matches suggestions and presens a selectable lists with suggestions to use
    • User can traverse suggestions with keyboard (arrows)
    • User can close suggestions by clicking out side of the autocomplete or pressing escape
    • The autocomplete can be string or tag based
    • Customizable trigger for when to trigger a match

    Init

    To initialize an autocomplete where you want string input, not tags, follow these steps:

    Add markup

    This markup is required.

    <div class="if input-wrapper autocomplete">
      <input type="search" class="if input-field" name="search" placeholder="Enter your search" aria-expanded="false" />
      <label for="search" class="if"> Search </label>
      <div class="if input-help">Tips: start searching: "how do i.."</div>
      <ol id="autocomplete-suggestions-2" role="listbox" class="if suggestions"></ol>
    </div>
    Add JavaScript
    By script tag
    <!-- Here we've just used a random name -->
    <script src="/autocomplete.string.js"></script>
    <script>
      const suggestions = [
        'how do i convert to pdf',
        'how do i convert to muslim',
        'how do i convert to judaism',
        'how do i convert to christianity',
        'how do i convert to catholic',
        'how do i convert to mp3'
      ];
      const autocompleteElements = document.querySelectorAll('.if.autocomplete:not(.tags)');
      const callback = value => {
        console.log(`Searching for ${value}`);
      };
      autocompleteElements.forEach(el => {
        autocomplete.initStringAutocomplete(el, {
          suggestions,
          callback,
          charLimit: 3,
          string: { IDS_TEMPLATE_STRING_NO_RESULTS: 'Ingen treff' }
        });
      });
    </script>
    As an ES6 module
    import autocomplete from '@if-design-system/autocomplete-js';
    
    const suggestions = [
      'how do i convert to pdf',
      'how do i convert to muslim',
      'how do i convert to judaism',
      'how do i convert to christianity',
      'how do i convert to catholic',
      'how do i convert to mp3'
    ];
    const autocompleteElements = document.querySelectorAll('.if.autocomplete:not(.tags)');
    const callback = value => {
      console.log(`Searching for ${value}`);
    };
    autocompleteElements.forEach(el => {
      autocomplete.initStringAutocomplete(el, {
        suggestions,
        callback,
        charLimit: 3,
        string: { IDS_TEMPLATE_STRING_NO_RESULTS: 'Ingen treff' }
      });
    });

    API

    initStringAutocomplete(el, options)

    Initializes the autocomplete with the given options.

    Param Type Description
    el HTMLElement The autocomplete element
    options AutocompleteOptions Options for the autocomplete
    el : HTMLElement

    The autocomplete DOM element:

    <div class="if input-wrapper autocomplete">
      <input type="search" class="if input-field" name="search" placeholder="Enter your search" aria-expanded="false" />
      <label for="search" class="if"> Search </label>
      <div class="if input-help">Tips: start searching: "how do i.."</div>
      <ol id="autocomplete-suggestions-2" role="listbox" class="if suggestions"></ol>
    </div>
    options : AutocompleteOptions Object

    A JavaScript object containing options for the autocomplete component.

    Type Default
    Object { suggestions: [], charLimit: 2 }
    Name Type Default Description
    suggestions Array/Function [] Either an array of strings to match, or a function returning a promise containing an arra to match
    charLimit Number 2
    callback Function A callback function that is called after user selects a suggestion. Takes the value of the selected item as an argument.
    options.suggestions : Array/Function
    Type Default
    Array/Function []

    This could either be:

    A: An array of suggestions, like:

    const suggestions = [
      'how do i convert to pdf',
      'how do i convert to muslim',
      'how do i convert to judaism',
      'how do i convert to christianity',
      'how do i convert to catholic',
      'how do i convert to mp3'
    ];

    or B: An async method (must return a promise) that fetches results to use as suggestions:

    const suggestions = query =>
      fetch(
        `https://services.odata.org/Northwind/Northwind.svc/Products?$format=json&$select=ProductID%2CProductName&$filter=indexof(ProductName%2C%20%27${query}%27)%20gt%20-1`
      )
        .then(response => response.json())
        .then(products => products.value.map(product => product.ProductName));
    };
    options.charLimit : Number

    A limit on when the autocomplete should start looking for matches. This might come in handy when used with fetch or any asynchronous call.

    Type Default value
    Number 2
    initTagsAutocomplete(el, options)

    The initialization and options are the same for initTagsAutocomplete(el, options) as for initStringAutocomplete(el, options). The key difference is the markup:

    <div class="if input-wrapper autocomplete tags">
      <input type="text" class="if input-field tag-holder" name="tags" value="Orwell, 1984" />
      <label for="tags" class="if"> Choose tags </label>
    
      <div class="if autocomplete-tags-input-holder">
        <ol id="autocomplete-suggestions-1" role="listbox" class="if suggestions"></ol>
        <button type="button" data-rel="Orwell" aria-label="Remove Orwell" class="if tag input">Orwell</button>
        <button type="button" data-rel="1984" aria-label="Remove 1984" class="if tag input">1984</button>
        <input
          name="autocomplete-1"
          type="text"
          aria-expanded="false"
          aria-owns="autocomplete-suggestions-1"
          aria-autocomplete="list"
          autocomplete="off"
          role="combobox"
          class="if input-field"
          data-size="largest"
        />
      </div>
      <span class="if input-help">
        Create tags by typing and use comma <kbd class="if">,</kbd> or <kbd class="if">Enter</kbd> to add them
      </span>
    </div>

    As you can see, you can also put predefined tags into the autocomplete.

    Tests

    To run tests:

    $ npm test
    Edit this section

    Contact us