PhoenixFormAwesomplete is a Phoenix function component that utilizes Lea Verou's autocomplete / autosuggest / typeahead / inputsearch Awesomplete widget, complying to accessibility standards (WCAG 2, Section 508).

It comes with an AwesompleteUtil javascript library which adds the following features:

• Dynamic remote data loading; based on what is typed-in it performs an ajax lookup.
• Allow HTML markup in the shown items. Show value with description. Optionally search in the description text.
• Show when there is an exact match.
• Show when there isn't a match.
• When there is an exact match show related data (supplied in the remote data) in other parts of the page.
• Select the highlighted item with the tab-key.

Online demo

Use cases

An autocomplete component is a free text input that provides suggestions while typing. It is not necessary to choose one of the suggestions, but of course a form validator can reject disallowed input.

The HTML combobox is very suitable for this. The combobox looks like a <select> but it doesn't limit the input. It consists of a <input type="text"> or <input type="search"> element combined with a <datalist> with <option> elements. The options cannot contain HTML markup.

When using LiveView the datalist of the HTML combobox can be made dynamic, with different suggestions based on the typed input. Like this dictionary search demo. However, when options are used with a text that differs from the value, the combobox will behave different in different browsers.

When the standard combobox doesn't meet the requirements, a solution involving javascript can be used. For LiveView there is for example this Live Select component, but this component is not compliant with accessibility standards.

This Awesomplete component can be applied for any of these cases:

• Use outside and inside LiveView. It is even possible to make a HEEx fragment with autocomplete that works in both. See the next chapter.
• It is specially suitable for suggestions supplied by HTTP web services that produce JSON. Although the default is to use Ajax calls, it is possible to use Phoenix channels. And, as long as the responses can be converted to Javascript arrays, it is also fine.
• When accessibility is important; the widget has been tested for accessibility (WCAG 2, Section 508).
• The list with suggestions can be customized, for example to show an extra description. Any HTML can be used in the suggestions.
• It can give suggestions for an input field with multiple values.
• It doesn't force the user to pick one of the suggestions; other values can be entered.
• It can highlight the input field when there is a match (green) or when there isn't (red).
• The client stops interacting with the backend, and filters on it's own when enough characters have been typed. This is when the suggestion list has become smaller than the search result limit. The client side filter is not affected by network latency, so it responds really quick.
• Search requests with their responses can be cached by the browser, if the web service sets HTTP Cache headers.
• A service worker can also be used for caching, if the standard ajax function is replaced with a function that uses the fetch api.
• It can fill dependent readonly fields/tags. The typical example would be a productcode with a product description shown in order lines. For the existing order lines the database can join the product description to be shown on the screen, but for new entries and when changing the productcode it has te be dynamicly looked up. The description can be shown in the suggestion list, and when one suggestion is selected the description can be shown near the combobox.

Phoenix function components

In HEEx templates and ~H sigils, function components offer a method of reuse. And they make the HEEx markup arguable more readable.

Use both inside and outside LiveView - via hooks

The beauty of the client hooks is that this can be used both inside and outside LiveView as they both use the mounted callback. This makes it possible define a reusable component with autocomplete fields, which can be incorporated inside and outside LiveView.

Example:

<.simple_form
  for={@form}
  id="list-form"
  phx-target={@myself}
  phx-change="validate"
  phx-submit="save"
>

  <.input field={@form[:country]} type="autocomplete" placeholder="Country" phx-debounce="blur" />

  <.autocomplete forField={@form[:country]}
                 url="https://restcountries.com/v2/all"
                 loadall="true"
                 prepop="true"
                 minChars="1"
                 maxItems="8"
                 value="name"
                 />

</.simple_form>copy

Why are hooks used instead of dynamically generated scripts?

For security reasons, LiveView doesn't execute the javascript in dynamicly loaded script tags. Adding new javascript after the page is loaded via the HTTP-request is what every malicious Cross Site Scripting (XSS) code tries to do. Via the Content-Security-Policy HTTP-header, it is possible to prevent dynamicly loaded scripts to be executed. In LiveView the javascript code is loaded as a static asset, and client hooks via the phx-hook can be used to execute javascript code for dynamicly added DOM elements. Instead of generating javascript code for every autocomplete field, a javascript hook is used which gets it's parameters at runtime.

Use outside LiveView, a.k.a. "dead" views - via page scripts

The advantage of embedded page scripts is that anonymous functions and functions defined on the same page can be used. It also offers a smoother migration path from PhoenixFormAwesomplete version 0.1. The EEx templates can be rewritten to use function components. The input tag is separated from the script tag of Awesomplete, which makes it easier to customize the style of the input field.

The <.autocomplete> tag in the HEEX template will produce a script in the HTML page.

Example:

<.simple_form :let={f} for={@changeset} action={@action}>

  <.input field={f[:country]} type="text" label="Country" />

  <.autocomplete forField={f[:country]}
                 url="https://restcountries.com/v2/all"
                 loadall="true"
                 prepop="true"
                 minChars="1"
                 maxItems="8"
                 value="name"
                 nonce={@script_src_nonce}
                 />

</.simple_form>copy

The nonce in the example above, is to allow the inline script to be executed in combination with a Content-Security-Policy that doesn't allow unsafe evals or unsafe inline scripts.

Security

Content-Security-Policy

As mentioned before, use a safe Content-Security-Policy (CSP):

• do not allow unsafe eval
• do not allow unsafe inline scripts
• In the connect_src whitelist only the url's of trusted sites. Make sure that the url's of Awesomplete cannot be tampered with.

Trusted web services

Use only trusted web services. As a safety measure against cross-site scripting (XSS) it is possible to sanatize or escape HTML in the JSON responses via a convertResponse function.

When an external web service is used directly, than this service will not only see the searched text but also the client IP address.

Most web services can only be accessed with a session cookie or a valid token in the request header. Use a custom ajax function to set withCredential to true on the XMLHttpRequest object to send session cookies, or set the necessairy request headers when XHR is in opened state.

Installation

Installation for using both inside and outside LiveView

• Add phoenix_form_awesompleteto the list of dependencies in mix.exs:

  def deps do
    [
    {:phoenix_form_awesomplete, "~> 1.0"}
    ]
  endcopy

• Run

  mix deps.get
  copy

• Add the import statement in assets/js/app.js

  import { AwesompleteUtil, attachAwesomplete, copyValueToId } from "phoenix_form_awesomplete"copy

• Add the Hooks Autocomplete and AutocompleteCopyValueToId in assets/js/app.js and pass the hooks to the LiveSocket

  let Hooks = {}
  
  // modified the LiveSocket params to add hooks
  let liveSocket = new LiveSocket("/live", Socket, {
    longPollFallbackMs: 2500,
    params: {_csrf_token: csrfToken},
    hooks: Hooks
  })
  
  const AU = AwesompleteUtil
      , customAwesompleteContext = {
  
    // These functions and objects can be referenced by name in the autocomplete function components.
    // This list can be customized.
  
    filterContains:   AU.filterContains
  , filterStartsWith: AU.filterStartsWith
  , filterWords:      AU.filterWords
  , filterOff:        AU.filterOff
  
  , item:             AU.item          // does NOT mark matching text
  // , itemContains:     AU.itemContains  // this is the default, no need to specify it.
  , itemStartsWith:   AU.itemStartsWith
  , itemMarkAll:      AU.itemMarkAll   // also mark matching text inside the description
  , itemWords:        AU.itemWords     // mark matching words
  
  , jsonFlatten:      AU.jsonFlatten   // Utility to flatten deep JSON structures
  
    // add your custom functions and/or lists here
  
  }
  
  Hooks.Autocomplete = {
    mounted() { attachAwesomplete(this.el, customAwesompleteContext, {} /* defaultSettings */ ) }
  }
  
  Hooks.AutocompleteCopyValueToId = {
    mounted() { copyValueToId(this.el) }
  }copy

• Add these function components in lib/<your_project>_web/components/core_components.ex:

  @awesomplete PhoenixFormAwesomplete.HookComponent
  
  defdelegate autocomplete(assigns), to: @awesomplete
  defdelegate copy_value_to_id(assigns), to: @awesomplete
  defdelegate copy_value_to_field(assigns), to: @awesompletecopy

• Add a new input type called autocomplete in lib/<your_project>_web/components/core_components.ex:

  The core_components.ex file may look different for every project, but here we assume there is a function to handle input for type="text". Copy this function to handle the new autocomplete type like in the example below. Pattern match the new type in the function argument.

  Surrounding the input tag there must be a span or div tag with a unique id, and with the phx‑update="ignore" attribute. LiveView should not do DOM updates on the input tag that is manipulated by the Awesomplete widget. The errors below the input field can and should be updated by LiveView.

  def input(%{type: "autocomplete"} = assigns) do
    assigns = assign(assigns, span_id: assigns.id <> "-domspace")
    ~H"""
    <div>
      <.label for={@id}><%= @label %></.label>
      <span phx-update="ignore" id={@span_id}>
        <input
          type="text"
          name={@name}
          id={@id}
          value={Phoenix.HTML.Form.normalize_value(@type, @value)}
          class={[
            "mt-2 block w-full rounded-lg text-zinc-900 focus:ring-0 sm:text-sm sm:leading-6"
          ]}
          {@rest}
        />
      </span>
      <.error :for={msg <- @errors}><%= msg %></.error>
    </div>
    """
  endcopy

  and add the autocomplete in the allowed types:

  attr :type, :string,
    default: "text",
    values: ~w(autocomplete checkbox color date datetime-local email file hidden month number password
               range radio search select tel text textarea time url week)copy

• Add in assets/css/app.css

  @import "../../deps/phoenix_form_awesomplete/priv/static/awesomplete_bundle.css";copy

  To modify this file, copy it to your assets/css directory and import that css file.

• Run

  mix phx.server
  copy

Installation for use outside LiveView only

• Add phoenix_form_awesompleteto the list of dependencies in mix.exs:

  def deps do
    [
    {:phoenix_form_awesomplete, "~> 1.0"}
    ]
  endcopy

• Run

  mix deps.get
  copy

• Add these function components in lib/<your_project>_web/components/core_components.ex:

  @awesomplete PhoenixFormAwesomplete.EmbedScriptComponent
  
  defdelegate autocomplete(assigns), to: @awesomplete
  defdelegate copy_value_to_id(assigns), to: @awesomplete
  defdelegate copy_value_to_field(assigns), to: @awesompletecopy

• Add this code in assets/js/app.js

  import { Awesomplete, AwesompleteUtil } from "phoenix_form_awesomplete"copy

• In lib/<your_project>_web/components/layouts/root.html.heex remove 'defer' for app.js:

  <script phx-track-static src={~p"/assets/js/app.js"}></script>copy

  Awesomplete and AwesompleteUtil must be loaded before running the inline scripts.
• Add in assets/css/app.css

  @import "../../deps/phoenix_form_awesomplete/priv/static/awesomplete_bundle.css";copy

  To modify this file, copy it to your assets/css directory and import that css file.
• Run

  mix phx.server
  copy

Accessibility

The Awesomplete widget is accessible (Section 508, WCAG). However, when using custom HTML in the suggestion list, this solution must be tested separately for compliance.

The red/green border color to indicate if there is a match or not is not helpful for people with red-green color blindness. The 2 pixel border size might be not enough for people with a low vision. And if they use a screen reader, the screen reader will paint it's own border around the focused element, hiding the red/green border color.

FAQ

Is it possible to use Phoenix channels instead of ajax web service calls?

Yes, the ajax call can be replaced.

As url we will use the keyword livesocket. Add this in assets/js/app.js after the declaration of liveSocket

function ajax2live(url, urlEnd, val, fn, xhr) {
  if (url && url.startsWith('livesocket:')) {
      const awe = this
          , phxEvent = url.substr(url.indexOf(':') + 1)
          , phxData = {'value':val, 'id':awe.input.id};
      // secretly use this internal function to push events
      liveSocket.execJSHookPush(awe.input, phxEvent, phxData, () => { console.log('sent ' + val); } );
  }
  else
  {
      AwesompleteUtil.ajax(url, urlEnd, val, fn, xhr);
  }
};copy

In assets/js/app.js add in customAwesompleteContext the name of the function above

  , ajax2live:  ajax2livecopy

In assets/js/app.js add in the mounted function, add a function to handle server response

const awe = attachAwesomplete(this.el, customAwesompleteContext, {} /* defaultSettings */ );
this.handleEvent(`update-list-${awe.input.id}`,
  ({searchResult, searchPhrase}) => { AwesompleteUtil.updateList(awe, searchResult, searchPhrase); }
);copy

In the HEEx template, in the .input add phx-target and in the .autocomplete refer to the new ajax function and change the url

<.input field={@form[:country]} type="text" placeholder="Country" phx-target={@myself} phx-debounce="blur" />

<.autocomplete
  forField={@form[:country]}
  url="livesocket:update-country-list"
  minChars="1"
  maxItems="5"
  ajax="ajax2live"
  />copy

Handle the event in LiveView:

def handle_event("update-country-list", %{"value" => val, "id" => id}, socket) do
  newCountryList = ... your query logic here ...
  {:noreply, push_event(socket, "update-list-#{id}", %{searchResult: newCountryList, searchPhrase: val})}
endcopy

On mobile devices the suggestions are shown behind the virtual keyboard. Do you have a solution?

With a bit of javascript it is possible to scroll up the input field to the top of the screen when suggestions are shown on small devices.

window.addEventListener('awesomplete-open', (el) => {
  if (window.innerWidth < 577 && window.innerHeight < 800) el.target.scrollIntoView();
});copy

Put this in scroll.js and add this javascript file in the header of the page.

Also, set maxItems to a low value when it is used on a small device.

Is it possible to group suggestions?

You can add the group in the description to show for each suggestion to which group it belongs, but the Awesomplete widget has not the option to show suggestions in groups.

Alternatives:

• Split the input in two fields: one to select the group, and in the autocomplete field show only items of the selected group.
• Use the HTML select element. It supports the optgroup tag.
• This javascript component autocomplete(r) from Denis Taran has a grouping feature.

Raw core example

IEx

iex> {:safe, [input, script]} = PhoenixFormAwesomplete.awesomplete(:user, :drinks,
...> ["data-list": "beer, gin, soda, sprite, water, vodga, whine, whisky"],
...> %{ minChars: 1 } )
iex> to_string input
"<input data-list=\"beer, gin, soda, sprite, water, vodga, whine, whisky\"" <>
" id=\"user_drinks\" name=\"user[drinks]\" type=\"text\">"
iex> script
"<script>AwesompleteUtil.start('#user_drinks', {}, {minChars: 1});</script>"copy

The first three parameters are passed on unchanged to the Phoenix form text_input which generates the input tag. minChars is an option for the Awesomplete object which is started with inline javascript. Just adding the multiple option changes the generated javascript code completely, the PhoenixFormAwesomplete module takes care of that. Instead of an server side generated data-list it is possible to specify an url of a JSON web service and let the client-code lookup the data list on-demand while typing. Look at the live examples with code.

It is possible to use aliases for the javascript library references in the generated page scripts via the environment variables util and awesomplete. The default names, AwesompleteUtil and Awesomplete respectively, are a bit long. This can shorten the average page size. For example use this javascript:

 var AU = AwesompleteUtil, AW = Awesomplete;copy

and change the variables via the application config:

 :phoenix_form_awesomplete, util:         "AU"
 :phoenix_form_awesomplete, awesomplete:  "AW"copy

After changing the config/config.exs run:

 mix deps.compile --force phoenix_form_awesompletecopy