feat(Autocomplete): add custom templates support

Author: mrholek

docs/assets/js/partials/snippets.js

@@ -277,6 +277,114 @@ export default () => {
   }
   // js-docs-end autocomplete-external-data
 
+  // js-docs-start autocomplete-custom-options
+  const myAutocompleteCountries = document.getElementById('myAutocompleteCountries')
+  const myAutocompleteCountriesAndCities = document.getElementById('myAutocompleteCountriesAndCities')
+
+  if (myAutocompleteCountries && myAutocompleteCountriesAndCities) {
+    const countries = [
+      {
+        value: 'pl',
+        label: 'Poland',
+        flag: '🇵🇱'
+      },
+      {
+        value: 'de',
+        label: 'Germany',
+        flag: '🇩🇪'
+      },
+      {
+        value: 'us',
+        label: 'United States',
+        flag: '🇺🇸'
+      },
+      {
+        value: 'es',
+        label: 'Spain',
+        flag: '🇪🇸'
+      },
+      {
+        value: 'gb',
+        label: 'United Kingdom',
+        flag: '🇬🇧'
+      }
+    ]
+
+    const cities = [
+      {
+        label: 'United States',
+        code: 'us',
+        flag: '🇺🇸',
+        options: [
+          {
+            value: 'au',
+            label: 'Austin'
+          },
+          {
+            value: 'ch',
+            label: 'Chicago'
+          },
+          {
+            value: 'la',
+            label: 'Los Angeles'
+          },
+          {
+            value: 'ny',
+            label: 'New York'
+          },
+          {
+            value: 'sa',
+            label: 'San Jose'
+          }
+        ]
+      },
+      {
+        label: 'United Kingdom',
+        code: 'gb',
+        flag: '🇬🇧',
+        options: [
+          {
+            value: 'li',
+            label: 'Liverpool'
+          },
+          {
+            value: 'lo',
+            label: 'London'
+          },
+          {
+            value: 'ma',
+            label: 'Manchester'
+          }
+        ]
+      }
+    ]
+
+    new coreui.Autocomplete(myAutocompleteCountries, {
+      cleaner: true,
+      indicator: true,
+      options: countries,
+      optionsTemplate(option) {
+        return `<div class="d-flex align-items-center gap-2"><span class="fs-5">${option.flag}</span><span>${option.label}</span></div>`
+      },
+      placeholder: 'Select country',
+      showHints: true,
+      search: 'global'
+    })
+
+    new coreui.Autocomplete(myAutocompleteCountriesAndCities, {
+      cleaner: true,
+      indicator: true,
+      options: cities,
+      optionsGroupsTemplate(optionGroup) {
+        return `<div class="d-flex align-items-center gap-2"><span class="text-body fs-5">${optionGroup.flag}</span><span>${optionGroup.label}</span></div>`
+      },
+      placeholder: 'Select city',
+      showHints: true,
+      search: 'global'
+    })
+  }
+  // js-docs-end autocomplete-custom-options
+
   // -------------------------------
   // Multi Selects
   // -------------------------------

docs/content/forms/autocomplete.md

@@ -216,6 +216,26 @@ Enable a cleaner button to quickly clear input element:
 <div data-coreui-toggle="autocomplete" data-coreui-cleaner="true" data-coreui-options="Angular, Bootstrap, React.js, Vue.js" data-coreui-placeholder="With cleaner button..."></div>
 {{< /example >}}
 
+## Custom templates
+
+The CoreUI Bootstrap Autocomplete Component provides the flexibility to personalize options and group labels by utilizing custom templates. You can easily customize the options using the `optionsTemplate`, and for groups, you can use `optionsGroupsTemplate`, as demonstrated in the examples below:
+
+{{< example stackblitz_pro="true" stackblitz_add_js="true">}}
+<div class="row">
+  <div class="col-md-6">
+    <div id="myAutocompleteCountries"></div>
+  </div>
+  <div class="col-md-6">
+    <div id="myAutocompleteCountriesAndCities"></div>
+  </div>
+</div>
+{{< /example >}}
+
+We use the following JavaScript to set up our autocomplete:
+
+{{< js-docs name="autocomplete-custom-options" file="docs/assets/js/partials/snippets.js" >}}
+
+
 ## Usage
 
 {{< bootstrap-compatibility >}}
@@ -261,21 +281,27 @@ const autoCompleteList = autoCompleteElementList.map(autoCompleteEl => {
 {{< bs-table >}}
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
+| `allowList` | object | `DefaultAllowlist` | Object containing allowed tags and attributes for HTML sanitization when using custom templates. |
 | `allowOnlyDefinedOptions` | boolean | `false` | Restricts selection to only predefined options when set to `true`. |
 | `ariaCleanerLabel` | string | `'Clear selection'` | Accessible label for the cleaner button, read by screen readers. |
 | `ariaIndicatorLabel` | string | `'Toggle visibility of options menu'` | Accessible label for the indicator button, read by screen readers. |
 | `cleaner` | boolean | `false` | Enables the selection cleaner button. |
 | `clearSearchOnSelect` | boolean | `true` | Clears the search input when an option is selected. |
 | `container` | string, element, boolean | `false` | Appends the dropdown to a specific element. Example: `container: 'body'`. |
 | `disabled` | boolean | `false` | Disables the component when set to `true`. |
-| `highlightOptionsOnSearch` | boolean | `true` | Highlights matching text in options during search. |
+| `highlightOptionsOnSearch` | boolean | `false` | Highlights matching text in options during search. |
+| `id` | string, null | `null` | Sets a custom ID for the component. If not provided, a unique ID is auto-generated. |
 | `indicator` | boolean | `false` | Enables the selection indicator button. |
 | `invalid` | boolean | `false` | Applies invalid styling to the component. |
 | `name` | string, null | `null` | Sets the name attribute for the input element. |
 | `options` | boolean, array | `false` | Array of options or option objects to populate the dropdown. |
+| `optionsGroupsTemplate` | function, null | `null` | Custom template function for rendering option group labels. Receives the group object as parameter. |
 | `optionsMaxHeight` | number, string | `'auto'` | Sets the maximum height of the options dropdown. |
+| `optionsTemplate` | function, null | `null` | Custom template function for rendering individual options. Receives the option object as parameter. |
 | `placeholder` | string, null | `null` | Placeholder text displayed in the input field. |
 | `required` | boolean | `false` | Makes the input field required for form validation. |
+| `sanitize` | boolean | `true` | Enables HTML sanitization for custom templates to prevent XSS attacks. |
+| `sanitizeFn` | function, null | `null` | Custom sanitization function. If provided, it will be used instead of the built-in sanitizer. |
 | `search` | array, string, null | `null` | Enables search functionality. Use `'global'` for global search across the component and `'external'` when options are provided from external sources. |
 | `searchNoResultsLabel` | string | `false` | Text displayed when no search results are found. |
 | `showHints` | boolean | `false` | Shows completion hints as users type. |

js/src/autocomplete.js

@@ -10,6 +10,7 @@ import BaseComponent from './base-component.js'
 import Data from './dom/data.js'
 import EventHandler from './dom/event-handler.js'
 import SelectorEngine from './dom/selector-engine.js'
+import { DefaultAllowlist, sanitizeHtml } from './util/sanitizer.js'
 import {
   defineJQueryPlugin,
   getNextActiveElement,
@@ -76,6 +77,7 @@ const SELECTOR_OPTIONS_EMPTY = '.autocomplete-options-empty'
 const SELECTOR_VISIBLE_ITEMS = '.autocomplete-options .autocomplete-option:not(.disabled):not(:disabled)'
 
 const Default = {
+  allowList: DefaultAllowlist,
   allowOnlyDefinedOptions: false,
   ariaCleanerLabel: 'Clear selection',
   ariaIndicatorLabel: 'Toggle visibility of options menu',
@@ -89,9 +91,13 @@ const Default = {
   invalid: false,
   name: null,
   options: false,
+  optionsGroupsTemplate: null,
   optionsMaxHeight: 'auto',
+  optionsTemplate: null,
   placeholder: null,
   required: false,
+  sanitize: true,
+  sanitizeFn: null,
   search: null,
   searchNoResultsLabel: false,
   showHints: false,
@@ -100,6 +106,7 @@ const Default = {
 }
 
 const DefaultType = {
+  allowList: 'object',
   allowOnlyDefinedOptions: 'boolean',
   ariaCleanerLabel: 'string',
   ariaIndicatorLabel: 'string',
@@ -113,9 +120,13 @@ const DefaultType = {
   invalid: 'boolean',
   name: '(string|null)',
   options: '(array|null)',
+  optionsGroupsTemplate: '(function|null)',
   optionsMaxHeight: '(number|string)',
+  optionsTemplate: '(function|null)',
   placeholder: '(string|null)',
   required: 'boolean',
+  sanitize: 'boolean',
+  sanitizeFn: '(null|function)',
   search: '(array|string|null)',
   searchNoResultsLabel: ('boolean|string'),
   showHints: 'boolean',
@@ -468,18 +479,33 @@ class Autocomplete extends BaseComponent {
     const _options = []
     for (const option of options) {
       if (option.options && Array.isArray(option.options)) {
+        const customGroupProperties = { ...option }
+
+        delete customGroupProperties.label
+        delete customGroupProperties.options
+
         _options.push({
+          ...customGroupProperties,
           label: option.label,
           options: this._getOptionsFromConfig(option.options)
         })
+
         continue
       }
 
       const label = typeof option === 'string' ? option : option.label
       const value = option.value ?? (typeof option === 'string' ? option : option.label)
       const isSelected = option.selected || (this._config.value && this._config.value === value)
 
+      const customProperties = typeof option === 'object' ? { ...option } : {}
+
+      delete customProperties.label
+      delete customProperties.value
+      delete customProperties.selected
+      delete customProperties.disabled
+
       _options.push({
+        ...customProperties,
         label,
         value,
         ...isSelected && { selected: true },
@@ -662,14 +688,21 @@ class Autocomplete extends BaseComponent {
         optgroup.setAttribute('role', 'group')
 
         const optgrouplabel = document.createElement('div')
-        optgrouplabel.textContent = option.label
+        if (this._config.optionsGroupsTemplate && typeof this._config.optionsGroupsTemplate === 'function') {
+          optgrouplabel.innerHTML = this._config.sanitize ?
+            sanitizeHtml(this._config.optionsGroupsTemplate(option), this._config.allowList, this._config.sanitizeFn) :
+            this._config.optionsGroupsTemplate(option)
+        } else {
+          optgrouplabel.textContent = option.label
+        }
+
         optgrouplabel.classList.add(CLASS_NAME_OPTGROUP_LABEL)
         optgroup.append(optgrouplabel)
 
         this._createOptions(optgroup, option.options)
         parentElement.append(optgroup)
 
-        return
+        continue
       }
 
       const optionDiv = document.createElement('div')
@@ -684,6 +717,10 @@ class Autocomplete extends BaseComponent {
       optionDiv.tabIndex = 0
       if (this._isExternalSearch() && this._config.highlightOptionsOnSearch && this._search) {
         optionDiv.innerHTML = this._highlightOption(option.label)
+      } else if (this._config.optionsTemplate && typeof this._config.optionsTemplate === 'function') {
+        optionDiv.innerHTML = this._config.sanitize ?
+          sanitizeHtml(this._config.optionsTemplate(option), this._config.allowList, this._config.sanitizeFn) :
+          this._config.optionsTemplate(option)
       } else {
         optionDiv.textContent = option.label
       }
@@ -693,10 +730,18 @@ class Autocomplete extends BaseComponent {
   }
 
   _onOptionsClick(element) {
-    if (!element.classList.contains(CLASS_NAME_OPTION) || element.classList.contains(CLASS_NAME_LABEL)) {
+    if (element.classList.contains(CLASS_NAME_LABEL)) {
       return
     }
 
+    if (!element.classList.contains(CLASS_NAME_OPTION)) {
+      element = element.closest(SELECTOR_OPTION)
+
+      if (!element) {
+        return
+      }
+    }
+
     const value = String(element.dataset.value)
     const foundOption = this._findOptionByValue(value)
 
@@ -804,7 +849,7 @@ class Autocomplete extends BaseComponent {
       if (option.textContent.toLowerCase().indexOf(this._search) === -1) {
         option.style.display = 'none'
       } else {
-        if (this._config.highlightOptionsOnSearch) {
+        if (this._config.highlightOptionsOnSearch && !this._config.optionsTemplate) {
           option.innerHTML = this._highlightOption(option.textContent)
         }