Combo Box - Single Select

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

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

Note

Combo Box 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 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 Combo Box as you want.

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

The combobox is also searchable, and has keyboard navigation.

Component

Vanilla JS

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

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

React

  <tpg-combo-box
    placeholder="Placeholder"
    id="combo-box-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>

Default value

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

Component

Vanilla JS

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

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

React

  <tpg-combo-box
    placeholder="Placeholder"
    selectedValue="4"
    label="Combox w/ scroll"
    ontpg-change={(e: TpgChangeEvent<string>) => {
      const combobox = e.target as ComboBox;
      combobox.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>

Icons

You can use the leading-icon-template attribute to set icon on both the Combo Box and the individual Menu Items.

If a selected Menu Item has a icon it will automatically override any that is set in the Combo Box.

Component

Vanilla JS

    <tpg-combo-box
      class="has-placeholder-icon"
      id="combo-box-1"
      label="My icon can be updated"
    >
    </tpg-combo-box>

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

    // Loop over all Comboboxes with placeholder icon
    const elemenetsWithPlaceholderIcon = document.querySelectorAll(
      "tpg-combo-box.has-placeholder-icon"
    );

    for (const elem of elemenetsWithPlaceholderIcon) {
      const combobox = elem as ComboBox;
      combobox.leadingIconTemplate = tpgIconPlaceholderCustom;
    }

    // Loop over all Menu Items with color lens icon
    const elementsWithColorlensIcon = document.querySelectorAll(
      "tpg-menu-item.has-colorlens-icon"
    );

    for (const elem of elementsWithColorlensIcon) {
      const combobox = elem as MenuItem;
      combobox.leadingIconTemplate = tpgIconColorLens;
    }
  });
</script>

React

<tpg-combo-box
  leadingIconTemplate={tpgIconPlaceholderCustom}
  placeholder="Placeholder"
  id="combo-box-1"
  label="My icon can be updated"
  ontpg-change={(e: TpgChangeEvent<string>) => {
    const combobox = e.target as ComboBox;
    combobox.selectedValue = e.value ?? '';
  }}
  options={[
      { value: "1", label: "Dancing Giraffes", leadingIconTemplate: {tpgIconColorLens} },
      { value: "2", label: "Space Chickens" },
      { value: "3", label: "Underwater Donuts" },
      { value: "4", label: "Turbo Sloths" }
    ]}
></tpg-combo-box>

Clear

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

Component

Vanilla JS

    <tpg-combo-box
      class="has-placeholder-icon"
      id="combo-box-1"
      label="My icon can be updated"
      clear-button
    >
    </tpg-combo-box>

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

React

<tpg-combo-box
  leadingIconTemplate={tpgIconPlaceholderCustom}
  placeholder="Placeholder"
  id="combo-box-1"
  label="My icon can be updated"
  clearButton
  ontpg-change={(e: TpgChangeEvent<string>) => {
    const combobox = e.target as ComboBox;
    combobox.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>

Full width

The Combo Box’s dropdown menu will by default scale to the width of its largest Menu Item. This behavior can be changed by including the full-width attribute, which causes it to scale with the width of the Combo Box itself.

Component

Vanilla JS

  <tpg-combo-box
    label="Dropdown has same width as combobox"
    full-width
  >
  </tpg-combo-box>

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

React

  <tpg-combo-box
    label="Dropdown has same width as combobox"
    ontpg-change={(e: TpgChangeEvent<string>) => {
      const combobox = e.target as ComboBox;
      combobox.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>

Event handling

The Combo Box 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 value, listen for this event and set the Combo Box’s selectedValue property manually based on the event’s payload.

Component

Vanilla JS

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

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

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

React

  <tpg-combo-box
    full-width
    label="Event being handled here"
    ontpg-change={(e: TpgChangeEvent<string>) => {
      const combobox = e.target as ComboBox;
      combobox.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>

  <tpg-combo-box
    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>

Tables

Properties

Attribute	Property	Description	Type	Default Value
options	options	Array of objects containing items to be listed	ComboBoxOption<unknown>[]	[]
max-rendered-options	maxRenderedOptions	Limits how many options are rendered	number	100
custom-render-menu-item	customRenderMenuItem	Custom render method	(option: FuzzyOption<unknown>) => TemplateResult | undefined | undefined
selected-value	selectedValue	Value of the currently selected menu item. 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
read-only	readOnly	Whether or not the combobox is read only	boolean	false
leading-icon-template	leadingIconTemplate	URI-encoded SVG template for the button's icon. Supported constants are found in	IconConstant | ''	''
should-sort	shouldSort	Whether the list should get sorted while searching.	boolean	true
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
No slots found.

CSS Parts

Attribute	Description
No CSS parts found.

Sandbox