Awesomplete is a front-end autocomplete tool that compares a user’s input to a defined data list, and if it recognises the input will make suggestions for the user to choose from.
We chose to use the Awesomplete tool in the Accord team while building the journey to enable users to create and submit their dispute. Awesomplete provided a neat solution to our problem of how to let the user choose the organisation they are raising a dispute against. The simplest solution would have been a dropdown list of all available organisations. However, as we will be working with ADR providers representing potentially hundreds or thousands of organisations, a dropdown list would not have been a feasible solution. Enter Awesomplete!
The Awesomplete documentation is very comprehensive. It is also easy to get started with the simplest version of an Awesomplete input, with very minimal code:
<input class="awesomplete"
data-list="Apples, Bananas, Grapes, Watermelons"/>
Once the Awesomplete libraries have been linked or added to your project, the only 2 requirements to make an Awesomplete input is the awesomplete CSS class on the input, and a linked data list. There are many ways to link a data list, from simply adding a data-list property, as above, to creating a new Awesomplete object in JavaScript.
It is also clear from the documentation how customisable Awesomplete is as a feature, especially when taking advantage of all the JavaScript properties available. You can quickly customise how many characters the user needs to type before Awesomplete will auto-complete, the number of suggested values Awesomplete will display to the user, and how the user can select their chosen suggested value. There are also custom DOM events, prefixed with awesomplete-, so that other actions on the page can be triggered by the user selecting an Awesomplete suggestion, or the Awesomplete pop-up appearing.
In the Accord app we have applied our existing CSS styles to the Awesomplete input for seamless styling. The user can either tab or click to select a suggested value. We have used additional Stimulus JavaScript controllers so that once the user’s input matches the data list, the prompt text will disappear and a submit button will appear so that the user can continue with the Create Dispute journey.
In the Accord app, we create an Awesomplete JavaScript object in our Stimulus controllers. On the one hand this gives us greater control in customising the input, but on the other hand it does rely on the user’s browser successfully loading JavaScript in order for the Awesomplete input to function. We overcome this challenge by first loading a Rails collection_select form tag. Then, if the JavaScript loads successfully, 3 things happen on page load: Firstly, the Stimulus controller extracts and stores the collection from the collection_select. Secondly, it creates an Awesomplete JavaScript object, using this saved collection as the data list. Finally, it removes the original collection_select from the page, so that only the Awesomplete input remains.
This solution presented its own challenge. A collection_select form helper accepts the label displayed to the user (e.g. “Squid Energy PLC”) and the value stored in the database (usually the ID) as separate arguments. An Awesomplete input does not have this distinction – the value it displays to the user is the same as the value it stores in the database on form submission. This is not ideal, as we are either trying to store a company name when the database is expecting an ID number, or we are displaying meaningless ID numbers to the user.
In the Accord app we overcome this by including a hidden field in the form. The Stimulus controller compares the user’s input to the stored data list. If it finds a match, it automatically populates the hidden field with the corresponding ID number for that organisation. In this way, the organisation’s label is displayed to the user so that they can easily recognise the organisation they’re raising a dispute against, whereas the organisation’s ID is what is submitted and stored in the database.
Overall, Awesomplete provided a good solution for our page. It is quick and simple to set up and implement, yet has the potential to be highly customisable and powerful. I hope these tips on how we overcame the challenges along the way are helpful to you in your project!
