feat(MultiSelect): add support for custom templates

mrholek · mrholek · commit 745c590aae7b · 2025-07-27T15:27:02.000+02:00
diff --git a/docs/assets/js/partials/snippets.js b/docs/assets/js/partials/snippets.js
@@ -397,22 +397,27 @@ export default () => {
       name: 'multiSelect',
       options: [
         {
-          value: 0,
-          text: 'Angular'
-        },
-        {
-          value: 1,
-          text: 'Bootstrap',
-          selected: true
-        },
-        {
-          value: 2,
-          text: 'React.js',
-          selected: true
-        },
-        {
-          value: 3,
-          text: 'Vue.js'
+          label: 'frontend',
+          options: [
+            {
+              value: 0,
+              text: 'Angular'
+            },
+            {
+              value: 1,
+              text: 'Bootstrap',
+              selected: true
+            },
+            {
+              value: 2,
+              text: 'React.js',
+              selected: true
+            },
+            {
+              value: 3,
+              text: 'Vue.js'
+            }
+          ]
         },
         {
           label: 'backend',
@@ -438,6 +443,114 @@ export default () => {
   }
   // js-docs-end multi-select-array-data
 
+  // js-docs-start multi-select-custom-options
+  const myMultiSelectCountries = document.getElementById('myMultiSelectCountries')
+  const myMultiSelectCountriesAndCities = document.getElementById('myMultiSelectCountriesAndCities')
+
+  if (myMultiSelectCountries && myMultiSelectCountriesAndCities) {
+    const countries = [
+      {
+        value: 'pl',
+        text: 'Poland',
+        flag: '🇵🇱'
+      },
+      {
+        value: 'de',
+        text: 'Germany',
+        flag: '🇩🇪'
+      },
+      {
+        value: 'us',
+        text: 'United States',
+        flag: '🇺🇸'
+      },
+      {
+        value: 'es',
+        text: 'Spain',
+        flag: '🇪🇸'
+      },
+      {
+        value: 'gb',
+        text: 'United Kingdom',
+        flag: '🇬🇧'
+      }
+    ]
+
+    const cities = [
+      {
+        label: 'United States',
+        code: 'us',
+        flag: '🇺🇸',
+        options: [
+          {
+            value: 'au',
+            text: 'Austin'
+          },
+          {
+            value: 'ch',
+            text: 'Chicago'
+          },
+          {
+            value: 'la',
+            text: 'Los Angeles'
+          },
+          {
+            value: 'ny',
+            text: 'New York'
+          },
+          {
+            value: 'sa',
+            text: 'San Jose'
+          }
+        ]
+      },
+      {
+        label: 'United Kingdom',
+        code: 'gb',
+        flag: '🇬🇧',
+        options: [
+          {
+            value: 'li',
+            text: 'Liverpool'
+          },
+          {
+            value: 'lo',
+            text: 'London'
+          },
+          {
+            value: 'ma',
+            text: 'Manchester'
+          }
+        ]
+      }
+    ]
+
+    new coreui.MultiSelect(myMultiSelectCountries, {
+      cleaner: true,
+      multiple: true,
+      options: countries,
+      optionsTemplate(option) {
+        return `<div class="d-flex align-items-center gap-2"><span class="fs-5">${option.flag}</span><span>${option.text}</span></div>`
+      },
+      placeholder: 'Select countries',
+      search: true,
+      selectionType: 'tags'
+    })
+
+    new coreui.MultiSelect(myMultiSelectCountriesAndCities, {
+      cleaner: true,
+      multiple: 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 cities',
+      search: true,
+      selectionType: 'tags'
+    })
+  }
+  // js-docs-end multi-select-custom-options
+
   // -------------------------------
   // Calendars
   // -------------------------------
diff --git a/docs/content/forms/multi-select.md b/docs/content/forms/multi-select.md
@@ -228,6 +228,25 @@ Add the `data-coreui-disabled="true"` boolean attribute to give it a grayed out
 </select>
 {{< /example >}}
 
+## Custom templates
+
+The CoreUI Bootstrap Multi Select 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">
+    <select id="myMultiSelectCountries" class="form-multi-select"></select>
+  </div>
+  <div class="col-md-6">
+    <select id="myMultiSelectCountriesAndCities" class="form-multi-select"></select>
+  </div>
+</div>
+{{< /example >}}
+
+We use the following JavaScript to set up our multi-select:
+
+{{< js-docs name="multi-select-custom-options" file="docs/assets/js/partials/snippets.js" >}}
+
 ## Sizing
 
 You may also choose from small and large multi selects to match our similarly sized text inputs.
@@ -333,6 +352,7 @@ const mulitSelectList = mulitSelectElementList.map(mulitSelectEl => {
 {{< bs-table >}}
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
+| `allowList` | object | `DefaultAllowlist` | Object containing allowed tags and attributes for HTML sanitization when using custom templates. |
 | `ariaCleanerLabel`| string | `Clear all selections` | A string that provides an accessible label for the cleaner button. This label is read by screen readers to describe the action associated with the button. |
 | `cleaner`| boolean | `true` | Enables selection cleaner element. |
 | `clearSearchOnSelect`| boolean | `false` | Clear current search on selecting an item. |
@@ -342,9 +362,14 @@ const mulitSelectList = mulitSelectElementList.map(mulitSelectEl => {
 | `multiple` | boolean | `true` | It specifies that multiple options can be selected at once. |
 | `name` | string, null | `null` | Set the name attribute for the native select element. |
 | `options` | boolean, array | `false` | List of option elements. |
+| `optionsGroupsTemplate` | function, null | `null` | Custom template function for rendering option group labels. Receives the group object as parameter. |
 | `optionsMaxHeight` | number, string | `'auto'` | Sets `max-height` of options list.	 |
 | `optionsStyle` | string | `'checkbox'` | Sets option style. |
+| `optionsTemplate` | function, null | `null` | Custom template function for rendering individual options. Receives the option object as parameter. |
 | `placeholder` | string | `'Select...'` | Specifies a short hint that is visible in the input. |
+| `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` | boolean, string | `false` | Enables search input element. When set to `'global'`, the user can perform searches across the entire component, regardless of where their focus is within the component. |
 | `searchNoResultsLabel` | string | `'No results found'` | Sets the label for no results when filtering.	|
 | `selectAll` | boolean | `true` | Enables select all button.|
diff --git a/js/src/multi-select.js b/js/src/multi-select.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,
@@ -83,6 +84,7 @@ const CLASS_NAME_TAG = 'form-multi-select-tag'
 const CLASS_NAME_TAG_DELETE = 'form-multi-select-tag-delete'
 
 const Default = {
+  allowList: DefaultAllowlist,
   ariaCleanerLabel: 'Clear all selections',
   cleaner: true,
   clearSearchOnSelect: false,
@@ -92,10 +94,14 @@ const Default = {
   multiple: true,
   name: null,
   options: false,
+  optionsGroupsTemplate: null,
   optionsMaxHeight: 'auto',
   optionsStyle: 'checkbox',
+  optionsTemplate: null,
   placeholder: 'Select...',
   required: false,
+  sanitize: true,
+  sanitizeFn: null,
   search: false,
   searchNoResultsLabel: 'No results found',
   selectAll: true,
@@ -107,6 +113,7 @@ const Default = {
 }
 
 const DefaultType = {
+  allowList: 'object',
   ariaCleanerLabel: 'string',
   cleaner: 'boolean',
   clearSearchOnSelect: 'boolean',
@@ -116,10 +123,14 @@ const DefaultType = {
   multiple: 'boolean',
   name: '(string|null)',
   options: '(boolean|array)',
+  optionsGroupsTemplate: '(function|null)',
   optionsMaxHeight: '(number|string)',
   optionsStyle: 'string',
+  optionsTemplate: '(function|null)',
   placeholder: 'string',
   required: 'boolean',
+  sanitize: 'boolean',
+  sanitizeFn: '(null|function)',
   search: '(boolean|string)',
   searchNoResultsLabel: 'string',
   selectAll: 'boolean',
@@ -407,18 +418,31 @@ class MultiSelect 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 value = String(option.value)
       const isSelected = option.selected || (this._config.value && this._config.value.includes(value))
 
+      const customProperties = typeof option === 'object' ? { ...option } : {}
+
+      delete customProperties.value
+      delete customProperties.selected
+      delete customProperties.disabled
+
       _options.push({
-        ...option,
+        ...customProperties,
         value,
         ...isSelected && { selected: true },
         ...option.disabled && { disabled: true }
@@ -691,7 +715,15 @@ class MultiSelect extends BaseComponent {
 
         optionDiv.dataset.value = String(option.value)
         optionDiv.tabIndex = 0
-        optionDiv.innerHTML = option.text
+
+        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.text
+        }
+
         parentElement.append(optionDiv)
       }
 
@@ -700,7 +732,15 @@ class MultiSelect extends BaseComponent {
         optgroup.classList.add(CLASS_NAME_OPTGROUP)
 
         const optgrouplabel = document.createElement('div')
-        optgrouplabel.innerHTML = 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)
 
@@ -737,10 +777,18 @@ class MultiSelect 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 { text } = this._findOptionByValue(value)
 
diff --git a/scss/forms/_form-multi-select.scss b/scss/forms/_form-multi-select.scss
@@ -414,7 +414,7 @@ select.form-multi-select {
     &::before {
       position: absolute;
       inset-inline-start: calc(var(--#{$prefix}form-multi-select-option-padding-x) * .5); // stylelint-disable-line function-disallowed-list
-      top: .7rem;
+      top: 50%;
       display: block;
       width: var(--#{$prefix}form-multi-select-option-indicator-width);
       height: var(--#{$prefix}form-multi-select-option-indicator-width);
@@ -425,6 +425,7 @@ select.form-multi-select {
       background-position: center;
       background-size: contain;
       border: var(--#{$prefix}form-multi-select-option-indicator-border);
+      transform: translateY(-50%);
       @include border-radius(var(--#{$prefix}form-multi-select-option-indicator-border-radius));
     }
   }
