Skip Navigation

Auto Suggest

Auto Suggest provides a short list of suggested responses based on a user’s input. The suggestions may include icons and other information to supplement the data.

Available in React

Auto Suggest

This example allows users to see a list of available options. The options narrow down as the user types.


When to Use

  • When it is possible to select from a broad list of options.
  • When the list of options from which to select is dynamic, like a list of crew members.

When Not to Use

  • When there is a short or predetermined list of options from which to select. Instead, consider a select input.
  • When multiple options may be selected. Consider a multi-select input instead.

Examples

Usage

  • In general, the Auto Suggest input field should stretch to fit the width of its container.
  • Keep suggested terms simple and concise, since lists that wrap are harder to scan.
  • Limit suggestions to 7 options (max), to prevent overwhelming the user with too many choices. If users require more context or assistance up front, a full list of options may be configured to display as soon as the field comes into focus. See the Developer tab for more information.

Content Options

To provide more clarity, additional content may display in the list of suggested options, such as iconography and auxiliary information.


Examples

Auto Suggest with Multiple Categories

This example allows users to view relevant options that are categorized into groups. Limit options to just a few per category, to prevent information overload.


When to Use

  • When multiple groups of options are presented in a single list.

When Not to Use

  • Do not use if you have a single category of options to display. Instead, consider adding iconography or text labels to individual options.

Auto Suggest with a Single Action

This example allows the addition of a single link that is related to the user’s search term.


When to Use

  • If added functionality can assist the user in making a selection or advancing through the process, such as a link to an Advanced Search on the user’s search term.

When Not to Use

  • For links that are not contextually related to the Auto Suggest search, such as a form of navigation.

Developer Notes

The Auto Suggest component is constructed using the spark-auto-suggest class. Contained within the component are a text field with the class spark-auto-suggest__field, a label with the class spark-label, an optional button with the class spark-auto-suggest__clear-btn, and a list element with the class spark-auto-suggest__listbox. The initial three elements are contained within a label element.

The component is instantiated using new Spark.AutoSuggest(el). The following options may be passed when using new Spark.AutoSuggest(el, {});:

Name Type Default Description
minLength number null The minimum number of characters required within the input field to trigger the Auto Suggest. If not passed, the component will check for the value of the data-min-length attribute if set.
maxSuggestions number 7 The maximum number of suggestions to show within the Auto Suggest list. If not passed, the component will check for the value of the data-max-suggestions attribute if set.
autoSuggestTerms array null An array containing the terms to be matched to the user input. This is required unless using a custom function for matching user input to Auto Suggest terms. The array can contain strings or objects. The object structure is: {value: "", icon: "", description: ""}. The icon and description properties are not required, and you can provide additional properties as well if integrating custom functionality.
showNoResultsFound parseBooleanAttribute null Whether a message indicating that no results were matched should be displayed. If not passed, the component will check for the value of the data-show-no-results-found attribute.
noResultsFoundText string No results found The text to display if showNoResultsFound is set to true.
showAllTerms boolean null Whether all Auto Suggest terms should be displayed when the Auto Suggest input field is initially focused on and has no content within it. If not passed, the component will check for the data-show-all-terms attribute.
customGetSuggestions function null A function to run to perform custom matching of terms.
onChange function null A callback function to run when the user inputs values into the Auto Suggest field. Callback arguments are newValue, instance.
onSelection function null A callback function to run when a suggestion is selected by pressing the Enter key or mouse click. As an example, it can be used to submit the form value of the Auto Suggest once a user has made their desired selection. Callback arguments are newValue, instance. The autoSuggestTerms array index of the selected item is made available via the selectedTermsObjectIndex property.
onEnterKey function null This has been deprecated in favor of onSelection above. A callback function to run when the Enter key is pressed. This can be used to submit the value of the Auto Suggest. Callback arguments are newValue, instance.

For all available methods and full API, refer to the component code on Bitbucket.

Auto Suggest

<div class="spark-auto-suggest" role="combobox" aria-expanded="false" aria-haspopup="listbox">
  <label>
    <input class="spark-auto-suggest__field" type="text" autocomplete="off" role="textbox" aria-labelledby="autosuggest1-label" aria-autocomplete="list" aria-controls="autosuggest1-listbox" aria-activedescendant="">
    <span id="autosuggest1-label" class="spark-label">Airline Search</span>
    <button type="button" class="spark-auto-suggest__clear-btn spark-icon-close" aria-label="Clear contents"></button>
  </label>

  <ul id="autosuggest1-listbox" class="spark-auto-suggest__listbox" role="listbox"></ul>
</div>

<style type="text/css">
  
</style>
// Vanilla JS
var terms = ["Air New Zealand", "Alaska Airlines" ... "Virgin Australia"];

var el = document.querySelector('.spark-auto-suggest');

var autoSuggestInstance = new Spark.AutoSuggest(el, {
  autoSuggestTerms: terms
});

Auto Suggest - Auxiliary Information

<div class="spark-auto-suggest example-auto-suggest--auxiliary-information" role="combobox" aria-expanded="false" aria-haspopup="listbox" data-show-no-results-found>
  <label>
    <input class="spark-auto-suggest__field" type="text" autocomplete="off" role="textbox" aria-labelledby="autosuggest5-label" aria-autocomplete="list" aria-controls="autosuggest5-listbox" aria-activedescendant="">
    <span id="autosuggest5-label" class="spark-label">Airline Search</span>
    <button type="button" class="spark-auto-suggest__clear-btn spark-icon-close" aria-label="Clear contents"></button>
  </label>

  <ul id="autosuggest5-listbox" class="spark-auto-suggest__listbox" role="listbox"></ul>
</div>

<style type="text/css">
  
</style>
// Vanilla JS
var terms = [
  {value: "Alaska Airlines"},
  {value: "Allegiant Air", category: "in Budget Airlines"},
  {value: "American Airlines", icon: "<span aria-hidden="true" class='spark-icon--fill spark-icon-airplane'></span>", description: "Description mauris consequat dignissim"},
  {value: "Delta Airlines", icon: "<span aria-hidden="true" class='spark-icon--fill spark-icon-airplane'></span>", description: "Description per inceptos himenaeos"},
  {value: "Frontier Airlines"},
  {value: "Hawaiian Airlines", category: "Description semper aliquam augue"},
  {value: "jetBlue", description: "Description ornare varius feugiat"},
  {value: "Southwest Airlines", icon: "<span aria-hidden="true" class='spark-icon--fill spark-icon-airplane'></span>", description: "Description tempor pretium"},
  {value: "Spirit Airlines", category: "in Budget Airlines"},
  {value: "United Airlines", icon: "<span aria-hidden="true" class='spark-icon--fill spark-icon-airplane'></span>"}
];

var el = document.querySelector('.spark-auto-suggest');

var autoSuggestInstance = new Spark.AutoSuggest(el, {
  autoSuggestTerms: terms
});

Auto Suggest - Error

<div class="spark-auto-suggest example-auto-suggest-error" role="combobox" aria-expanded="false" aria-haspopup="listbox" data-error="true">
  <label>
    <input class="spark-auto-suggest__field" type="text" autocomplete="off" role="textbox" aria-labelledby="autosuggest6-label" aria-autocomplete="list" aria-controls="autosuggest6-listbox" aria-activedescendant="">
    <span id="autosuggest6-label" class="spark-label">Airline Search</span>
    <button type="button" class="spark-auto-suggest__clear-btn spark-icon-close" aria-label="Clear contents"></button>
  </label>
  <ul id="autosuggest6-listbox" class="spark-auto-suggest__listbox" role="listbox"></ul>
  <span class="spark-input__message">Please select a valid airline</span>
</div>

<style type="text/css">
  
</style>
// Vanilla JS
var terms = ["Air New Zealand", "Alaska Airlines" ... "Virgin Australia"];

var el = document.querySelector('.spark-auto-suggest');

var autoSuggestInstance = new Spark.AutoSuggest(el, {
  autoSuggestTerms: terms,
  onSelection: function(val, inst) {
    inst.clearError();
  },
  onChange: function(val, inst) {
    if (terms.includes(val)) {
      inst.clearError();
    }
    else {
      inst.setError();
    }
  }
});

Auto Suggest - Show All Terms

<div class="spark-auto-suggest" role="combobox" aria-expanded="false" aria-haspopup="listbox" data-show-all-terms>
  <label>
    <input class="spark-auto-suggest__field" type="text" autocomplete="off" role="textbox" aria-labelledby="autosuggest1-label" aria-autocomplete="list" aria-controls="autosuggest1-listbox" aria-activedescendant="">
    <span id="autosuggest1-label" class="spark-label">Airline Search</span>
    <button type="button" class="spark-auto-suggest__clear-btn spark-icon-close" tabindex="-1" aria-label="Clear contents"></button>
  </label>

  <ul id="autosuggest1-listbox" class="spark-auto-suggest__listbox" role="listbox"></ul>
</div>

<style type="text/css">
  
</style>
// Vanilla JS
var terms = ["Air New Zealand", "Alaska Airlines" ... "Virgin Australia"];

var el = document.querySelector('.spark-auto-suggest');

var autoSuggestInstance = new Spark.AutoSuggest(el, {
  autoSuggestTerms: terms
});

To create an Auto Suggest that shows all terms on initial focus, add a data-show-all-terms attribute to the spark-auto-suggest element or pass

Auto Suggest - Show No Results Found

<div class="spark-auto-suggest example-auto-suggest--auxiliary-information" role="combobox" aria-expanded="false" aria-haspopup="listbox" data-show-no-results-found>
  <label>
    <input class="spark-auto-suggest__field" type="text" autocomplete="off" role="textbox" aria-labelledby="autosuggest5-label" aria-autocomplete="list" aria-controls="autosuggest5-listbox" aria-activedescendant="">
    <span id="autosuggest5-label" class="spark-label">Airline Search</span>
    <button type="button" class="spark-auto-suggest__clear-btn spark-icon-close" aria-label="Clear contents"></button>
  </label>

  <ul id="autosuggest5-listbox" class="spark-auto-suggest__listbox" role="listbox"></ul>
</div>

<style type="text/css">
  
</style>
// Vanilla JS
var terms = ["Air New Zealand", "Alaska Airlines" ... "Virgin Australia"];

var el = document.querySelector('.spark-auto-suggest');

var autoSuggestInstance = new Spark.AutoSuggest(el, {
  autoSuggestTerms: terms
});

Auto Suggest with Multiple Categories

<div class="spark-auto-suggest example-auto-suggest--multiple-categories" role="combobox" aria-expanded="false" aria-haspopup="listbox">
  <label>
    <input class="spark-auto-suggest__field" type="text" autocomplete="off" role="textbox" aria-labelledby="autosuggest4-label" aria-autocomplete="list" aria-controls="autosuggest4-listbox" aria-activedescendant="">
    <span id="autosuggest4-label" class="spark-label">Airline Search</span>
    <button type="button" class="spark-auto-suggest__clear-btn spark-icon-close" aria-label="Clear contents"></button>
  </label>

  <ul id="autosuggest4-listbox" class="spark-auto-suggest__listbox" role="listbox"></ul>
</div>

<style type="text/css">
  
</style>
// Vanilla JS

// THE FOLLOWING IS CUSTOM JS CODE - IT DOES USE PORTIONS FROM THE AUTO SUGGEST COMPONENT JS

var categoryWeights = {
  "africa": 4,
  "asia": 3,
  "europe": 2,
  "north america": 1,
  "south america": 5
};

var terms = [
  {value: "Virgin Atlantic", category: "Europe"},
  {value: "Norwegian Air", category: "Europe"},
  {value: "Finnair", category: "Europe"},
  {value: "KLM", category: "Europe"},
  {value: "Air France", category: "Europe"},
  {value: "Austrian", category: "Europe"},
  {value: "Swiss Airlines", category: "Europe"},
  {value: "Turkish Airlines", category: "Europe"},
  {value: "Lufthansa", category: "Europe"},
  {value: "Alaska Airlines", category: "North America"},
  {value: "Delta", category: "North America"},
  {value: "JetBlue", category: "North America"},
  {value: "Hawaiian Airlines", category: "North America"},
  {value: "Southwest", category: "North America"},
  {value: "United Airlines", category: "North America"},
  {value: "American Airlines", category: "North America"},
  {value: "Egypt Air", category: "Africa"},
  {value: "Kenya Airways", category: "Africa"},
  {value: "South African Airways", category: "Africa"},
  {value: "Royal Air Maroc", category: "Africa"},
  {value: "Air Mauritius", category: "Africa"},
  {value: "Avianca", category: "South America"},
  {value: "LAN Airlines", category: "South America"},
  {value: "TAM Airlines", category: "South America"},
  {value: "Azul Airlines", category: "South America"},
  {value: "Gol", category: "South America"},
  {value: "Asiana", category: "Asia"},
  {value: "Japan Airlines", category: "Asia"},
  {value: "Thai Airways", category: "Asia"},
  {value: "Hainan Airlines", category: "Asia"},
  {value: "Etihad", category: "Asia"},
  {value: "EVA Air", category: "Asia"},
  {value: "Cathay Pacific", category: "Asia"},
  {value: "Singapore Airlines", category: "Asia"},
  {value: "Emirates", category: "Asia"},
  {value: "All Nippon Airways", category: "Asia"},
  {value: "Qatar", category: "Asia"}
];

var getSuggestions = function() {
  var matchedCategories = [];
  var results = [];

  for (var i = 0; i < this.autoSuggestTerms.length; i++) {
    var term = this.termsObject ? this.autoSuggestTerms[i].value : this.autoSuggestTerms[i];

    if (term.toLowerCase().indexOf(this.inputEl.value.toLowerCase()) !== -1) {
      var regex = new RegExp(this.inputEl.value, 'gi');
      var suggestion = term.replace(regex, function(string){
        return '<mark>' + string + '</mark>';
      });

      if (this.termsObject) {
        // Add HTML wrapper around suggestion
        suggestion = '<span class="spark-auto-suggest__list-item__value" data-suggestion-category="' + this.autoSuggestTerms[i].category + '">' + suggestion + '</span>';

        // Matched categories
        matchedCategories.push(this.autoSuggestTerms[i].category);
      }

      results.push(suggestion);
    }

    if (results.length === this.maxSuggestions) {
      break;
    }
  }

  if (results.length) {
    // Get the distinct categories in our results
    matchedCategories = matchedCategories.filter(function(value, index, self){
      return self.indexOf(value) === index;
    });

    // Get the right order based on weights
    matchedCategories = matchedCategories.sort(function(a, b){
      if (categoryWeights[a.toLowerCase()] < categoryWeights[b.toLowerCase()]) {
        return -1;
      }
      if (categoryWeights[a.toLowerCase()] > categoryWeights[b.toLowerCase()]) {
        return 1;
      }
      return 0;
    });

    // Create list items
    var counter = 0;

    matchedCategories.forEach(function(matchedCategory){
      var catItem = document.createElement('li');
      catItem.setAttribute('role', 'presentation');
      catItem.setAttribute('class', 'spark-auto-suggest__list-category');
      catItem.innerHTML = matchedCategory;

      this.listBoxEl.appendChild(catItem);

      for (var j = 0; j < results.length; j++) {
        if ( results[j].toLowerCase().indexOf(matchedCategory.toLowerCase()) !== -1 ) {
          var resultItem = document.createElement('li');
          resultItem.setAttribute('role', 'option');
          resultItem.setAttribute('id', 'spark-auto-suggest__list-item--' + counter);
          resultItem.setAttribute('class', 'spark-auto-suggest__list-item');

          if (this.termsObject) {
            resultItem.setAttribute('data-suggestion-object', true);
          }

          resultItem.setAttribute('tabindex', '-1');
          resultItem.innerHTML = results[j];

          this.listBoxEl.appendChild(resultItem);
          counter++;
        }
      }
    }.bind(this));

    this._openListbox();
    this.resultsCount = results.length;
  }
  else {
    this.resultsCount = 0;

    if (this.showNoResultsFound) {
      var noResult = document.createElement('li');
      noResult.setAttribute('role', 'presentation');
      noResult.setAttribute('class', 'spark-auto-suggest__list-item spark-auto-suggest__list-item--no-results');
      noResult.innerHTML = this.noResultsFoundText;
      this.listBoxEl.appendChild(noResult);

      this._openListbox();
    }
  }
}

var autosuggests = document.querySelectorAll('.spark-auto-suggest');
for(var k = 0, len = autosuggests.length; k < len; k++) {
  new Spark.AutoSuggest(autosuggests[k], {
    'autoSuggestTerms': terms,
    'customGetSuggestions': getSuggestions
  });
}

A custom function is required to create an Auto Suggest with grouped Categories. This is because it might be necessary to apply different weights to the categories instead of merely displaying the first few matched terms and their categories, or an alphabetical list of categories. A custom function also allows you to perform your own custom regex matching of terms if desired.

Auto Suggest with a Single Action

<div class="spark-auto-suggest example-auto-suggest--single-action" role="combobox" aria-expanded="false" aria-haspopup="listbox">
  <label>
    <input class="spark-auto-suggest__field" type="text" autocomplete="off" role="textbox" aria-labelledby="autosuggest3-label" aria-autocomplete="list" aria-controls="autosuggest3-listbox" aria-activedescendant="">
    <span id="autosuggest3-label" class="spark-label">Airline Search</span>
    <button type="button" class="spark-auto-suggest__clear-btn spark-icon-close" aria-label="Clear contents"></button>
  </label>

  <ul id="autosuggest3-listbox" class="spark-auto-suggest__listbox" role="listbox"></ul>
</div>

<style type="text/css">
  
</style>
// Vanilla JS

// THE FOLLOWING IS CUSTOM JS CODE - IT DOES USE PORTIONS FROM THE AUTO SUGGEST COMPONENT JS

var terms = ["Air New Zealand", "Alaska Airlines", "All Nippon Airways", "American Airlines", "British Airways", "Cathay Pacific Airways", "Emirates", "Etihad Airways", "EVA Air", "Finnair", "Hawaiian Airlines", "Japan Airlines", "KLM", "Lufthansa", "Qantas", "Royal Jordanian Airlines", "SAS", "Singapore Airlines", "Southwest", "Swiss", "United Airlines", "Virgin Atlantic", "Virgin Australia"];

var getSuggestions = function() {
  var results = [];

  for (var i = 0; i < this.autoSuggestTerms.length; i++) {
    var term = this.autoSuggestTerms[i];

    if (term.toLowerCase().indexOf(this.inputEl.value.toLowerCase()) !== -1) {
      var regex = new RegExp(this.inputEl.value, 'gi');
      var suggestion = term.replace(regex, function(string){
        return '<mark>' + string + '</mark>';
      });

      results.push(suggestion);
    }

    if (results.length === this.maxSuggestions) {
      break;
    }
  }

  if (results.length) {
    var linkID;

    for (var j = 0; j < results.length; j++) {
      var resultItem = document.createElement('li');
      resultItem.setAttribute('role', 'option');
      resultItem.setAttribute('id', 'spark-auto-suggest__list-item--' + j);
      resultItem.setAttribute('class', 'spark-auto-suggest__list-item');
      resultItem.setAttribute('tabindex', '-1');
      resultItem.innerHTML = results[j];

      this.listBoxEl.appendChild(resultItem);
      linkID = j;
    }

    // Append divider and link
    var divider = document.createElement('li');
    divider.setAttribute('role', 'presentation');
    divider.setAttribute('aria-hidden', 'true');
    divider.setAttribute('class', 'spark-auto-suggest__list-divider');
    this.listBoxEl.appendChild(divider);

    linkID++;
    var link = document.createElement('li');
    link.setAttribute('role', 'option');
    link.setAttribute('id', 'spark-auto-suggest__list-item--' + linkID);
    link.setAttribute('class', 'spark-auto-suggest__list-item spark-auto-suggest__list-item--action');
    link.setAttribute('tabindex', '-1');
    link.innerHTML = '<a href="" class="spark-link" tabindex="-1">Separate Link</a>';
    this.listBoxEl.appendChild(link);

    this._openListbox();
    this.resultsCount = results.length + 1;
  }
}

var autosuggests = document.querySelectorAll('.spark-auto-suggest');
for(var k = 0, len = autosuggests.length; k < len; k++) {
  new Spark.AutoSuggest(autosuggests[k], {
    'autoSuggestTerms': terms,
    'customGetSuggestions': getSuggestions
  });
}

Similar to the previous Multiple Categories example, a custom function is required to create an Auto Suggest with a Single Action link appended to the Auto Suggest list. This is because the appended link could be contextual to the user’s input.

Additional Notes

  • While the Auto Suggest is designed to stretch to the full width of its container, there might be a need to adjust this to suit a particular design. If that is the case, ensure that the minimum width for the suggested options overlay is 296px, though the field itself may be smaller.
  • If working with a custom implementation, ensure that the <mark> element is used to highlight the additional text string, rather than the text that the user has entered when matching input to a result set. This makes it easier for the user to scan for the differences between options.
  • If looking to use the component’s rendering functionality but with a dynamic list of terms, you can update the contents of the terms array/object by accessing it via the instance of the component.
  • If the Auto Suggest needs to be disabled, ensure that the disabled attribute is applied to the spark-auto-suggest__field element as well as the spark-auto-suggest__clear-btn element if it is in use.

Accessibility Notes

The overarching Auto Suggest component and the child elements found within it require additional attributes to make the component more accessible to assistive technologies. These attributes are discussed below:

Parent Auto Suggest Container

The spark-auto-suggest element requires the following attributes:

  • A role="combobox" attribute to identify the component as a combobox element.
  • An aria-expanded="false" attribute that indicates that the listbox element of the component is not displayed. This will be toggled by Javascript depending on the state of the listbox.
  • An aria-haspopup="listbox" attribute that indicates that the component can popup a listbox to suggest values.

Auto Suggest Text Input

Similar to the parent spark-auto-suggest element, spark-auto-suggest__field input requires the following attributes:

  • An aria-labelledby="" attribute with the value set to the id of the element that has the text to be used as a label for the field. In the provided examples, a spark-label element is included with the text to make available.
  • An aria-autocomplete="list" to indicate that the autocomplete behavior of the input field is to present a list of possible values in a popup and that these suggestions are related to the value currently present in the input field.
  • An aria-controls="" attribute with the value set to the id of the listbox element.
  • An aria-activedescendant="" with no value set. As a user interacts with the component, the value will be updated based on the user’s selection.

Auto Suggest Listbox

The Listbox is the container that displays suggestions to users. This container needs to be “connected” to the other elements described above using the following attributes:

  • An id attribute whose value is used as the value for the aria-controls attribute found on the input field.
  • A role="listbox" attribute to identify the list as a listbox.

Other ARIA attributes that apply to the list items are managed by Javascript.

Icons in Auto Suggest Results

When using Spark Icons as part of an Auto Suggest result set, as shown in the Content Options examples above, aria-hidden attributes should be set to spark-icon elements unless the icons are intended to be announced to users. If the latter, use aria-label attributes to provide additional content and context to users.