Autosuggest

This is a simple markup pattern designed to be used as the basis for an autosuggest solution.

This is the template markup.

<div class="form-item form-item--autosuggest">
      <input type="text">
      <ul class="autosuggest" autosuggest-state="hidden">
          <li class="autosuggest__result"> /* result goes here */ </li>
          <li class="autosuggest__result"> /* result goes here */ </li>
          <li class="autosuggest__result"> /* result goes here */ </li>
          // and so on...            
      </ul>
  </div>

The results can contain any html markup including the content-columns grid if needed. Please note: if you want to set the number of items to show you will have to recalculate the max-height according to the height of your li elements.

To show the results simply change the value of the attribute autosuggest-state to visible

<div class="form-item form-item--autosuggest">
      <input type="text">
      <ul class="autosuggest" autosuggest-state="visible">
          <li class="autosuggest__result"> /* result goes here */ </li>
          <li class="autosuggest__result"> /* result goes here */ </li>
          <li class="autosuggest__result"> /* result goes here */ </li>
          // and so on...            
      </ul>
  </div>

Example

The result list can be populated before or after showing. Simply update the contents of the ul

If there are no results, you can add the class .autosuggest__result--no-result to the li to get an error styling.

<div class="form-item form-item--autosuggest">
      <input type="text">
      <ul class="autosuggest" autosuggest-state="hidden">
          <li class="autosuggest__result autosuggest__result--no-result">No results message</li>
      </ul>
  </div>

Example

  • No results message
The default amount of results to show is five, any more than this will activate native scrolling behaviour. You can override this by applying a max-height as an inline style to the ul

The height of the results are fixed to 2.15rem so simply calculate the max height by using the following formula max-height = r * (2.15rem + 4px) + 5px where r is the number of results you wish to show. To simplify this we suggest using the inbuilt CSS calc function (see example)

<div class="form-item form-item--autosuggest">
      <input type="text">
      <ul class="autosuggest" autosuggest-state="hidden" style="max-height:calc(10 * (2.15rem + 8px) + 5px)"> // This shows 10 results before scrolling
          <li class="autosuggest__result">Alpha</li>
          <li class="autosuggest__result">Beta</li>
          <li class="autosuggest__result">Gamma</li>
          <li class="autosuggest__result">Delta</li>
          <li class="autosuggest__result">Epsilon</li>
          <li class="autosuggest__result">Alpha</li>
          <li class="autosuggest__result">Beta</li>
          <li class="autosuggest__result">Gamma</li>
          <li class="autosuggest__result">Delta</li>
          <li class="autosuggest__result">Epsilon</li>
          <li class="autosuggest__result">Alpha</li>
          <li class="autosuggest__result">Beta</li>
          <li class="autosuggest__result">Gamma</li>
          <li class="autosuggest__result">Delta</li>
          <li class="autosuggest__result">Epsilon</li>
          <li class="autosuggest__result">Alpha</li>
          <li class="autosuggest__result">Beta</li>
          <li class="autosuggest__result">Gamma</li>
          <li class="autosuggest__result">Delta</li>
          <li class="autosuggest__result">Epsilon</li>  
      </ul>
  </div>

Example

  • Alpha
  • Beta
  • Gamma
  • Delta
  • Epsilon
  • Alpha
  • Beta
  • Gamma
  • Delta
  • Epsilon
  • Alpha
  • Beta
  • Gamma
  • Delta
  • Epsilon
  • Alpha
  • Beta
  • Gamma
  • Delta
  • Epsilon

We have also added some styling for indicating which part of the result has been matched. Simply surround the characters with a <b> tag.

<div class="form-item form-item--autosuggest">
      <input type="text">
      <ul class="autosuggest" autosuggest-state="hidden">
          <li class="autosuggest__result">Q<b>uia</b> voluptatibus</li>
          <li class="autosuggest__result">Dolor aper<b>uia</b>m</li>
          <li class="autosuggest__result">Eos repell<b>uia</b>t ipsum</li>
      </ul>
  </div>
  • Quia voluptatibus
  • Dolor aperuiam
  • Eos repelluiat ipsum

Accessibility

In addition to the functional styling markup above. To ensure the autosuggest box remains accessible to the visually impaired or those using other input methods, please follow the following guidelines.

<div class="form-item form-item--autosuggest">
        <input type="text" aria-autocomplete="list" aria-label="autosuggest" role="combobox" aria-owns="autosuggest-result" aria-activedescendant="selected-option">
        <ul role="listbox" autosuggest-state="hidden" id="autosuggest-results" class="autosuggest" aria-expanded="false" tabindex="-1"> 
            <li role="option" class="autosuggest__result" id="alpha">Alpha</li>
            <li role="option" class="autosuggest__result" id="beta">Beta</li>
            <li role="option" class="autosuggest__result" id="gamma">Gamma</li>
            // and so on...
        </ul>
    </div>

When displaying the suggestions by changing the autosuggest-state attribute to visible. You should also change the aria-expanded attribute to true and back to false again when hidden.

You must also handle shifting focus to the <ul> containing the suggestions and allow selection of the <li> elements using the keyboard arrows. In addition to this you will need to update the aria-activedescendant attribute on the input tag with the value of the currently selected option.


If in any doubt about these requirements please review the specification

Behaviour

@todo add behaviour guidelines DF-539

Please consult the UX team regarding behviour in the meantime.