Autocomplete

[govuk-design-system]

What

A text input that suggests options to the user as they type.

Why

Anything else

• Example: View the demo
• Read the draft guidance on Dropbox Paper
• Download the code from GitHub

[hannalaakso]

Current status of autocomplete work

We currently have accessible autocomplete and "country picker" prototypes.

Country picker consumes both accessible autocomplete and picker engine through npm. The latter contains the sorting and synonyms functionality.

Feedback from @edwardhorsford suggests that the sorting and synonym logic in the picker engine is particularly coupled up with the country data and should stay as its own entity. Additionally, the picker engine has a jQuery dependency in Twitter's Bloodhound that it consumes.

We should therefore build the sorting and synonyms logic separately in accessible autocomplete.

We could look at the picker engine sorting functionality for ideas for sorting. It:

1. Matches exact canonical name
2. Matches start of canonical name
3. Matches start of another word in canonical name (eg Kingdom in United Kingdom)
4. Exactly matches synonym
5. Matches start of synonym
6. Matches start of another word in synonym
7. Matches within words in canonical (not the start - doesn’t work anyway)
8. Matches within words in synonym (not the start - doesn’t work anyway)

Each of these gives a score - we then sort by score by using a score, we can also have biases on some entries - which multiply the score this means that an entry with a bias of 2x (eg UK) will rise in the rankings, but not necessarily to the top, if it was only a very low score to begin with (thanks Ed!)

Here's an example (thanks Ed!) of what the current autocomplete without sorting logic does (only sorts alphabetically):

The example doesn't show synonyms but if we had them, it would make sense to rank canonical names higher than (potentially obscure) synonyms.

We should also test that the country picker that consumes accessible autocomplete remains functional.

What could be the MVP?

Features to discuss are:

• sorting
• synonyms
• typo fixing
• weighting (biased results)

We could also consider deprecating some existing functionality in accessible autocomplete (and potentially bring some of it back in at a later point):

• Internationalisation
• React support
• placeholder
• showAllValues

Some examples of Accessible Autocomplete synomym logic that don't depend on jQuery

1. @frankieroberto has built a government organisation autocomplete that uses the accessible autocomplete and accepts alternative names.

2. The TEN prototype contains a simple example of synonym matching.

Should we continue to use Preact with the accessible autocomplete?

The current autocomplete imports Preact which is an alternative React, a library for building interactive UIs, and extends the Preact events.

If we were to switch to not using a JavaScript framework, we could give ourselves an awful lot of work to solve the problem of managing interactivity and state that has already been solved well in Preact. As Preact is only 3kb in weight and supports Progressive Enhancement (so that if the browser doesn't run JavaScript the user is presented with the native select element), it would seem sensible to continue using it.

[joelanman]

My 2 cents:

I think an MVP should be as minimal as possible while giving value.

I think the results algorithm should be plug-in able if possible, so people can write their own if needed, or extend the default.

I think we need sorting, as otherwise very unexpected results can happen as seen in the gif in the comment above.

I don't think we need synonyms, weighting or typo fixing for an MVP - not all autocomplete use cases will need them.

Not sure why we would remove functionality that exists, unless there's a reason for removing them?

[hannalaakso]

The deprecation suggestion was due to the fact that at the moment we are getting issues raised for things like the autocomplete not working with the latest version of React. It's good to support React if there's a need but as we're still trying to move out of the prototype phase I think we should probably focus our efforts for now on getting the core product working.

[ashleyanderton]

Have there been any updates / recommendations on this? We've integrated autocomplete using jQuery UI due to a number of technical limitations. Bit of a write up below:

Our challenge - Autocomplete with a dynamic dataset

We looked at GDS's accessible autocomplete but limitations prevented us from using it. Due to the fact that the dataset being called on was dynamic we couldn't rely on the GDS default which is designed to work with pre-defined data sets (for example countries). We instead are making a call to our search service as the user types which ultimately meant we had to use a different library, jquery UI.

jquery UI Autocomplete: https://jqueryui.com/autocomplete/

Accessibility

The use of jquery UI was tested over multiple rounds of end to end accessibility testing and no issues were flagged. For those users who do not have javascript enabled the suggestions simply did not appear, this did not massively inhibit the use of the search function at all though.

Engagement

Overall engagement with our version of autocomplete has been higher than expected. The following shows a comparison of those who performed a search vs those who interacted with autocomplete whilst doing so.

Interacted with search: 19687
Used autocomplete suggestion: 5375

That's 27.3% of users engaging with autocomplete

[joelanman]

Hi, @ashleyanderton thanks for your comment, and for sharing your research.

The GDS Accessible Autocomplete can be used with a dynamic dataset, using the source option. You can provide a function which can query your dynamic dataset and return results.

There's documentation and an example of a custom source function here: https://github.com/alphagov/accessible-autocomplete#source

Let me know if you try it and get any problems.

[ashleyanderton]

Cheers @joelanman looks like this has been updated since we last investigated! (We integrated this almost a year ago now).

Good news though, we'll look to integrate Accessible Autocomplete and let you know how we get on.

[trevorkapswarah]

Hi @joelanman , I work with @ashleyanderton and we have now integrated the accessible autocomplete and we are pulling in from a dynamic source with no problem,

The only issue/concern is that the input box is autogenerated by the library, are there any plans to allow the users to specify an existing input box?

I can appreciate that if JS disabled the autocomplete functionally would not work but we still need the input box as it would serve more than one purpose, in our case we use the input box value to run a search on a server.

[hannalaakso]

Hi @trevorkapswarah

Glad you've got it working. Is the issue you reported that you can currently progressively enhance only <select> elements whereas you need to progressively enhance <input type="text"> (as your list of options is too large to include in a select)?

[edwardhorsford]

Progressively enhancing an input was always something we planned for. My (now foggy) memory suggests there was some issue with IDs or something that prevented us doing it at the time - it would be good if it could be looked at though for services which need to be able to support users providing answers that can't be known in advance.

[trevorkapswarah]

Hi @hannalaakso

Thanks for the response.

We would like to manually add an input element in our view markup and then bind that input element to the GDS autocomplete functionality.

<label for="my-autocomplete">GDS Accessibility Search</label>
<div id="my-autocomplete-container"></div>

---

var element = document.querySelector('#my-autocomplete-container');
var id = 'my-autocomplete';
accessibleAutocomplete({
element: element,
id: id,
name: 'SearchTerm',
minLength : 3,
source: suggest
});

We are happy with the other config options used on initialising the library functionality and can specify properties for the input box generated by the library.

@edwardhorsford yes it would be ideal for progressive enhancement of an existing input element

[hannalaakso]

Thanks @trevorkapswarah.

It looks like this issue has been raised previously as well: alphagov/accessible-autocomplete#213

Would you be okay to comment on that issue with your use case and requirements? 🙏

[adamsilver]

DfE Apply for teacher training has used this component really successfully and it has tested well in an accessibility audit ran by DAC 10 December 2019.

During their audit, they specifically praised this component (which doesn't surprise me as it's so hard to get right).

But one tester struggled to type their nationality, ‘British’, into the box and wanted the ability to select it from a list like a traditional select box.

I know that the Autocomplete component can be configured such that an arrow appears and the user can reveal all the options but @edwardhorsford also told me that enabling this feature caused many users to select from the list instead of typing because they weren't aware the autocomplete behaviour existed.

So it appears we're in a bit of a rock and hard place:

• styling as a normal text box (default behaviour which is how we have it on our service) doesn't signify what the input can do (make suggestions)
• applying a down arrow (through configuration on the autocomplete) makes it look like users have to select from a list like a select box even if they would have preferred to type and get suggestions more quickly.

I wonder if this component needs different visual treatment to signify that this is a special type of component, different to a select box and and text box.

[np-phillips-dft]

Currently using the autocomplete in a DfT system for users to apply for training funding. The autocomplete suggests all the items in the source and has tested well with users.

One use case, which was also questioned in a GDS beta assessment, was what happens if the item is not in the list? Currently there is no way to capture the user entered text if it is not in the source list.

We took the, not ideal, option of altering the JS to output a value into an attribute:

Is it possible to capture the user text, if it is not in the source list ,in a proper attribute? It might be a use case outside of the intended functionality but it would prevent altering the component which causes a maintenance overhead.

[msmithcti]

We're using this pattern on the Report wreck material service (Maritime & Coastguard Agency) and it's quite an interesting use case where this pattern has been very useful.

We've used it to consistently capture information about a shipwrecked vessel, which seems simple on the face of it but actually has some complications. The name of a shipwreck can be a known vessel name (hence the autocomplete) but if the name is not known then often communities make up names, such as 'bottle wreck' (because there were lots of bottles found on it). Even where the vessel name is known, it's not always simple as multiple ships can have the same name. This means the construction and sunk year are often very important too.

In terms of processing, autocomplete is important to ensure we're not getting multiple spellings of the same vessel and to ensure reports from the same vessel are linked together to aid in dealing with the reports.

Our solution includes the construction and sunk years alongside the vessel name in the autocomplete:

On selection of a vessel within the autocomplete, we automatically populate the construction and sunk year fields too:

We do this through an onConfirm handler within the accessible autocomplete options:

onConfirm: function onConfirm(val) {
  if (val && val.constructed) {
    document.getElementById('wreck-construction-year').value = val.constructed;
  }
  if (val && val.sunk) {
    document.getElementById('wreck-sunk-year').value = val.sunk;
  }
}

So far our user research suggests this solution works well for our use case.