jQuery UI Autocomplete deprecated in favor of @drupal/a11y_autocomplete library

jQuery UI has reached end of life and is being phased out of Drupal core as a result. jQuery UI autocomplete has been deprecated as part of that process. and Autocomplete functionality is now provided by a new library, @drupal/a11y_autocomplete.

Although autocomplete inputs will no longer use jQuery UI to execute their functionality, two backwards compatibility layers have been provided to make this change minimally disruptive. For the vast majority of use cases,

API backwards compatiblity

By default, autocomplete-enabled inputs include a backwards-compatible shim so the jQuery UI autocomplete API will continue to work for most use cases. For example, usage such as $('#autocomplete-input').autocomplete(options); will continue to work as expected despite jQuery UI autocomplete not being loaded. When the jQuery UI autocomplete API is used, a a JavaScript deprecation notice will be triggered.

API Backwards compatibility scope

• All Autocomplete specific functionality is supported (i.e. everything documented in the jQuery UI Autocomplete API) This includes:
  • Options: appendTo, autoFocus, classes, delay, disabled, minLength, position, source
  • Methods: close, destroy, disable, enable, instance, option, search, widget
  • Events: change, close, create, focus, open, response, search, select
  • Extension Points: _renderItem, _renderMenu, _resizeMenu
• Extending jQuery UI functionality viajQuery UI widget factory has limited backwards compatibility support. If a site codebase has no calls to $.widget('[a string that includes "autocomplete"]'), then it is not impacted by this backwards compatibility limitation.

  When using the widget factory to extend autocomplete, such as with calls like this $.widget( "custom.autocomplete", {foo: bar, dip: dobson});, only autocomplete-specific methods (close, destroy, disable, enable, instance, option, search, widget) will be overridden. This widget factory usage does not support widget-scoped methods such as _addClass, _create, _delay,, _destroy, _superetc. Code that attempts to use these methods will fail ungracefully in order to unambiguously convey the fact that this usage is no longer supported. If a given autocomplete implementation includes this now-unsupported use case, this will be immediately apparent in the JS console as soon as the page loads.

jQuery UI Autocomplete Options -> A11y_Autocomplete Equivalents

autocompleteInstance.appendList = function() {
  document.body..appendChild(this.ul);
}

document.addEventListener('drupal-autocomplete-init', (e) => {
  // Get the autocomplete instance
  const { instance } = e.detail;
  // Equivalent to setting a class via classes.ui-autocomplete
  instance.ul.classList.add('TheClassYouWantAddedToTheList');
  // Equivalent to setting a class via classes.ui-autocomplete-input
  instance.input.classList.add('TheClassYouWantAddedToTheInput');
});

autocompleteInput.addEventListener('autocomplete-pre-search', (e) => {
  // Get the autocomplete instance if needed.
  const { instance } = e.detail;
  // Doing this is the equivalent of setting the disabled option to true;
  e.preventDefault();  
});

jQuery UI Autocomplete Methods -> A11y_Autocomplete Equivalents

autocompleteInput.addEventListener('autocomplete-pre-search', (e) => {
  // Get the autocomplete instance if needed.
  const { instance } = e.detail;
  
  if (theCriteriaYouWantItToBeDisabled) {
    // PreventDefault here is the equivalent of calling disable
    e.preventDefault();  
 }

});

// A11yAutocomplete expects the input to be focused when a search
// occurs, even if it's programmatically triggered.
autocompleteInstance.input.focus();

// Set the value of the input with the term to search for 
autocompleteInstance.input.value = 'valueBeingSearchedFor';

// Trigger a search. It is important to add the keydown event as an arg, otherwise <code>doSearch

jQuery UI Autocomplete Events -> A11y_Autocomplete Equivalents

jQuery UI Autocomplete Extension Points -> A11y_Autocomplete Equivalents

autocompleteInput.addEventListener('autocomplete-open', (e) => {
  // Get the autocomplete instance if needed.
  const { instance } = e.detail;
  // Example: dhange list item attributes
 this.ul.children.forEach((item) => {
  item.setAttribute('data-attribute-to-set', 'value being set');
});

});

autocompleteInput.addEventListener('autocomplete-open', (e) => {
  // Get the autocomplete instance if needed.
  const { instance } = e.detail;
  // Example: change an attribute in the rendered list
  instance.ul.setAttribute('data-attribute-to-set', 'value being set');
});

autocompleteInput.addEventListener('autocomplete-open', (e) => {
  // Get the autocomplete instance
  const { instance } = e.detail;
  // Example: set size of the rendered list
  instance.ul.style.width = '500px';
});

This API backwards compatibility shim will be removed in Drupal 10. For sites that still require the jQuery UI autocomplete in Drupal 10, jQuery UI autocomplete is still available as a contributed module https://www.drupal.org/project/jquery_ui_autocomplete/.

Running the API shim

By default, the shim is enabled on all autocomplete-enabled inputs initialized by Drupal.autocomplete. It may be necessary for contributed projects to have to manually initialize the shim when upgrading to use the new autocomplete library. The shim will reduce the likely hood of causing regressions with other modules that are potentially working on top of the contributed project.

It is important to attach the jQuery UI shim with the assumption that it might not always exist because the jQuery UI shim will be removed in Drupal 10.

1. Add dependency for the core/autocomplete.jqueryui.shim library.

   library:
     ...
     dependencies:
       - core/autocomplete.jqueryui.shim
   

2. Attach jQuery UI shim after initializing the autocomplete library:

   const autocomplete = A11yAutocomplete(input, options);
   
   // Drupal.autocompleteShim is removed in Drupal 10. If it doesn't exist, the
   // shim doesn't have to be initialized.
   if (Drupal.autocompleteShim && autocomplete._internal_object) {
     Drupal.autocompleteShim.jqueryUiShimInit(autocomplete._internal_object, options);
   }
   

Markup backwards compatibility

The markup generated by A11y_Autocomplete is different than that generated by jQuery UI autocomplete. Themes declaring Stable or Stable 9 as a base theme will continue to render autocomplete inputs with markup matching jQuery UI's. For sites needing to maintain jQuery UI markup, but not able to use Stable/Stable 9 as as base theme, it is also possible to provide backwards compatible markup by copying js/autocomplete from Stable or Stable 9 (they are identical) and loading it via a custom module or theme. If your site does not include autocomplete-specific custom styling or JavaScript customizations that rely on a specific DOM structure, this layer is likely unnecessary.