Combo Box - Multi Select

<tpg-combo-box-multiselect></tpg-combo-box-multiselect>

Combo box Multi Select elicits a multi-level list of drop-down choices that can contain values ot itemized options. When the dropdown is empty, the ComboBoxMultiselect will be set to “disabled” with N/A as its content.

Note

Combo Box Multi Select behaves differently than other list elements. Instead of using slots, it relies on the prop options, which should be an array of objects instead of html elements.

Examples

The Combo Box Multi Select also has the same properties/attributes as Text Field. You can check the Text Field page for its available attributes.

Basic Usage

Pass as many options into the Mutliselect Combo Box as you want.

When more than 10 options are put into the combo-box-multiselect, the dropdown menu will automatically become scrollable. The amount of rendered items is determined by maxRenderedOptions prop.

The mutli select combo box is also searchable, and has keyboard navigation.

Component

Vanilla JS

      <tpg-combo-box-multiselect
        placeholder="Placeholder"
        id="combo-box-multiselect-1"
        label="Combox w/ scroll"
      ></tpg-combo-box-multiselect>

      <script>
        document.addEventListener('DOMContentLoaded', ()=>{
          // Add event listener to change selection upon clicking a Menu Item
          const multiselectComboBoxes = document.querySelectorAll('tpg-combo-box-multiselect');
          for (const multiselectComboBox of multiselectComboBoxes) {
            multiselectComboBox.options = [
              { value: "1", label: "Dancing Giraffes" },
              { value: "2", label: "Space Chickens" },
              { value: "3", label: "Underwater Donuts" },
              { value: "4", label: "Turbo Sloths" }
            ];
            multiselectComboBox.addEventListener("tpg-change", (e) => {
              e.target.selectedValue = e.value;
            });
          }
        });
      </script>

React

      <tpg-combo-box-multiselect
        placeholder="Placeholder"
        id="combo-box-multiselect-1"
        label="Combox w/ scroll"
        options={[
          { value: "1", label: "Dancing Giraffes" },
          { value: "2", label: "Space Chickens" },
          { value: "3", label: "Underwater Donuts" },
          { value: "4", label: "Turbo Sloths" }
        ]}
      ></tpg-combo-box-multiselect>

Default value

Use the selected-values attribute on the Combo Box Multi Select to set the default selected values. The value has to correspond with the value of a Menu Item.

Component

Vanilla JS

      <tpg-combo-box-multiselect
        placeholder="Placeholder"
        label="This icon can be overridden"
      >
      </tpg-combo-box-multiselect>

      <script>
        document.addEventListener('DOMContentLoaded', ()=>{
          // Add event listener to change selection upon clicking a Menu Item
          const multiselectComboBoxes = document.querySelectorAll('tpg-combo-box-multiselect');
          for (const multiselectComboBox of multiselectComboBoxes) {
            multiselectComboBox.options = [
              { value: "1", label: "Dancing Giraffes" },
              { value: "2", label: "Space Chickens" },
              { value: "3", label: "Underwater Donuts" },
              { value: "4", label: "Turbo Sloths" }
            ];
            multiselectComboBox.selectedValue = "4";
            multiselectComboBox.addEventListener("tpg-change", (e) => {
              e.target.selectedValue = e.value;
            });
          }
        });
      </script>

React

  <tpg-combo-box-multiselect
    placeholder="Placeholder"
    selectedValue="4"
    label="Combox w/ scroll"
    ontpg-change={(e: TpgChangeEvent<string>) => {
      const multiselectComboBox = e.target;
      multiselectComboBox.selectedValue = e.value ?? '';
    }}
    options={[
      { value: "1", label: "Dancing Giraffes" },
      { value: "2", label: "Space Chickens" },
      { value: "3", label: "Underwater Donuts" },
      { value: "4", label: "Turbo Sloths" }
    ]}
  ></tpg-combo-box-multiselect>

Clear

You can use the clear-button attribute to easily clear the input of Combo Box Multi Select

Component

Vanilla JS

      <tpg-combo-box-multiselect
        placeholder="Placeholder"
        label="Clearable"
      >
      </tpg-combo-box-multiselect>

      <script>
        document.addEventListener('DOMContentLoaded', ()=>{
          // Add event listener to change selection upon clicking a Menu Item
          const multiselectComboBoxes = document.querySelectorAll('tpg-combo-box-multiselect');
          for (const multiselectComboBox of multiselectComboBoxes) {
            multiselectComboBox.options = [
              { value: "1", label: "Dancing Giraffes" },
              { value: "2", label: "Space Chickens" },
              { value: "3", label: "Underwater Donuts" },
              { value: "4", label: "Turbo Sloths" }
            ];
            multiselectComboBox.selectedValue = "4";
            multiselectComboBox.addEventListener("tpg-change", (e) => {
              e.target.selectedValue = e.value;
            });
          }
        });
      </script>

React

  <tpg-combo-box-multiselect
    placeholder="Placeholder"
    selectedValue="4"
    label="Clearable"
    ontpg-change={(e: TpgChangeEvent<string>) => {
      const multiselectComboBox = e.target;
      multiselectComboBox.selectedValue = e.value ?? '';
    }}
    options={[
      { value: "1", label: "Dancing Giraffes" },
      { value: "2", label: "Space Chickens" },
      { value: "3", label: "Underwater Donuts" },
      { value: "4", label: "Turbo Sloths" }
    ]}
  ></tpg-combo-box-multiselect>

Read Only

Use the read-only attribute on the Combo Box Multi Select to showcase the value without being able to change it.

Component

Vanilla JS

      <tpg-combo-box-multiselect
        placeholder="Placeholder"
        read-only
      >
      </tpg-combo-box-multiselect>

      <script>
        document.addEventListener('DOMContentLoaded', ()=>{
          // Add event listener to change selection upon clicking a Menu Item
          const multiselectComboBoxes = document.querySelectorAll('tpg-combo-box-multiselect');
          for (const multiselectComboBox of multiselectComboBoxes) {
            multiselectComboBox.options = [
              { value: "1", label: "Dancing Giraffes" },
              { value: "2", label: "Space Chickens" },
              { value: "3", label: "Underwater Donuts" },
              { value: "4", label: "Turbo Sloths" }
            ];
            multiselectComboBox.selectedValue = "4";
            multiselectComboBox.addEventListener("tpg-change", (e) => {
              e.target.selectedValue = e.value;
            });
          }
        });
      </script>

React

  <tpg-combo-box-multiselect
    placeholder="Placeholder"
    selectedValue="4"
    readOnly
    ontpg-change={(e: TpgChangeEvent<string>) => {
      const multiselectComboBox = e.target as multiselectComboBox;
      multiselectComboBox.selectedValue = e.value ?? '';
    }}
    options={[
      { value: "1", label: "Dancing Giraffes" },
      { value: "2", label: "Space Chickens" },
      { value: "3", label: "Underwater Donuts" },
      { value: "4", label: "Turbo Sloths" }
    ]}
  ></tpg-combo-box-multiselect>

Event handling

The Combo Box Multi Select is a controlled component, which means its selection state must be managed externally by your application logic.

When a Menu Item is selected, the component dispatches a tpg-change event. To update the selected values, listen for this event and set the Combo Box Multi Select’s selectedValues property manually based on the event’s payload.

Component

Vanilla JS

      <tpg-combo-box-multiselect full-width class="handle-change" label="Event being handled here">
      </tpg-combo-box-multiselect>

      <tpg-combo-box-multiselect full-width label="No event handling">
      </tpg-combo-box-multiselect>

      <script>
        document.addEventListener('DOMContentLoaded', ()=>{
          // Add event listener to change selection upon clicking a Menu Item
          const multiselectComboBoxes = document.querySelectorAll('tpg-combo-box-multiselect.handle-change');
          for (const multiselectComboBox of multiselectComboBoxes) {
            multiselectComboBox.options = [
              { value: "1", label: "Dancing Giraffes" },
              { value: "2", label: "Space Chickens" },
              { value: "3", label: "Underwater Donuts" },
              { value: "4", label: "Turbo Sloths" }
            ];
            multiselectComboBox.addEventListener("tpg-change", (e) => {
              e.target.selectedValue = e.value;
            });
          }
        });
      </script>

React

      <tpg-combo-box-multiselect
        full-width
        label="Event being handled here"
        ontpg-change={(e: TpgChangeEvent<string>) => {
          const multiselectComboBox = e.target;
          multiselectComboBox.selectedValue = e.value ?? '';
        }}
        options={[
          { value: "1", label: "Dancing Giraffes" },
          { value: "2", label: "Space Chickens" },
          { value: "3", label: "Underwater Donuts" },
          { value: "4", label: "Turbo Sloths" }
        ]}
      ></tpg-combo-box-multiselect>

      <tpg-combo-box-multiselect
        full-width
        label="No event handling"
        options={[
          { value: "1", label: "Dancing Giraffes" },
          { value: "2", label: "Space Chickens" },
          { value: "3", label: "Underwater Donuts" },
          { value: "4", label: "Turbo Sloths" }
        ]}
        ></tpg-combo-box-multiselect>

Tables

Properties

Attribute	Property	Description	Type	Default Value
options	options	Array of objects containing items to be listed	ComboBoxOption[]	[]
max-rendered-options	maxRenderedOptions	Limits how many options are rendered	number	100
selected-values	selectedValues	Values of the currently selected menu items. Can be used to preselect a Menu Item should their values match.	string[]	[]
label	label	Label of the textfield.	string	''
value	value	The default value on the textfield	string	''
message	message	Message to appear on badge if set.	string	''
placeholder	placeholder	Optional placeholder that is visible if value is empty	string	''
type	type	The type of textfield to render in terms of severity-level.	'default' | 'error' | 'warning' | 'danger'	'default'
clear-button	clearButton	Flag that includes a button to clear the text if included.	boolean	false
full-width	fullWidth	Determines if the dropdown menu scales to its parent (text-field) or if it scales to its largest menu item..	boolean	false
disabled	disabled	Whether or not the combobox is disabled	boolean	false
leading-icon-template	leadingIconTemplate	URI-encoded SVG template for the button's icon. Supported constants are found in	IconConstant | ''	''
read-only	readOnly	Whether or not the multi select is read only	boolean	false
form-associated	formAssociated		boolean	true
name	name	name property for use in conjunction with html forms	string

Events

Event name	Reactjs attribute	Description
tpg-change	ontpg-change	Emitted when an item is selected, containing the value identifier of this item.

Functions

Name	Description	Arguments
No functions found.

Slots

Name	Description
	Slot menu-items in here.

CSS Parts

Attribute	Description
No CSS parts found.

Sandbox