Combobox

A select-like button with rich options, search and multiple selection, built on the menu.

Bootstrap’s combobox docs describe the markup and CSS.

Example

Point a bsCombobox button at a bsComboboxMenu of bsComboboxOption buttons. Its value is the selected option’s value, bound with [formControl], [(ngModel)], [formField] or [(value)]. The menu opens with a click, Enter, Space or the arrow keys, and arrow keys move between options.

Value: none

<button
  type="button"
  bsCombobox
  placeholder="Choose a fruit…"
  aria-label="Fruit"
  [menu]="fruits"
  [(value)]="fruit"></button>
<div bsComboboxMenu #fruits="bsComboboxMenu">
  <button type="button" bsComboboxOption value="apple">Apple</button>
  <button type="button" bsComboboxOption value="banana">Banana</button>
  <button type="button" bsComboboxOption value="cherry">Cherry</button>
  <button type="button" bsComboboxOption value="grape">Grape</button>
</div>
<p class="mt-3 mb-0 fg-3">Value: {{ fruit() ?? 'none' }}</p>

With form field

In a bsFormField, the label names the combobox, and help text and feedback describe it. The combobox follows its form control’s validation state.

PlanYou can change plans at any time.

Please choose a plan.

<div bsFormField>
  <label bsFormLabel>Plan</label>
  <button
    type="button"
    bsCombobox
    placeholder="Choose a plan…"
    [menu]="plans"
    [formControl]="plan"></button>
  <div bsComboboxMenu #plans="bsComboboxMenu">
    <button type="button" bsComboboxOption value="free">Free</button>
    <button type="button" bsComboboxOption value="pro">Pro</button>
    <button type="button" bsComboboxOption value="team">Team</button>
  </div>
  <small bsFormText>You can change plans at any time.</small>
  <div bsInvalidFeedback>Please choose a plan.</div>
</div>

Custom content

Options are ordinary buttons, so they can hold icons (.menu-item-icon) and descriptions (.menu-item-content and .menu-item-description). The combobox shows the first .menu-item-content span, or set label on the option. Set check on the menu for check marks on selected options.

<div class="d-flex flex-wrap gap-3">
  <button
    type="button"
    bsCombobox
    placeholder="Choose a language…"
    aria-label="Language"
    [menu]="languages"
    [(value)]="language"></button>
  <div bsComboboxMenu #languages="bsComboboxMenu">
    <button type="button" bsComboboxOption value="html">
      <svg
        class="menu-item-icon"
        width="16"
        height="16"
        fill="currentColor"
        viewBox="0 0 16 16"
        aria-hidden="true">
        <path
          d="M14 4.5V14a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V2a2 2 0 0 1 2-2h5.5zm-3 0A1.5 1.5 0 0 1 9.5 3V1H4a1 1 0 0 0-1 1v12a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1V4.5z" />
      </svg>
      <span>HTML</span>
    </button>
    <button type="button" bsComboboxOption value="css">
      <svg
        class="menu-item-icon"
        width="16"
        height="16"
        fill="currentColor"
        viewBox="0 0 16 16"
        aria-hidden="true">
        <path
          d="M14 4.5V14a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V2a2 2 0 0 1 2-2h5.5zm-3 0A1.5 1.5 0 0 1 9.5 3V1H4a1 1 0 0 0-1 1v12a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1V4.5z" />
      </svg>
      <span>CSS</span>
    </button>
    <button type="button" bsComboboxOption value="js">
      <svg
        class="menu-item-icon"
        width="16"
        height="16"
        fill="currentColor"
        viewBox="0 0 16 16"
        aria-hidden="true">
        <path
          d="M14 4.5V14a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V2a2 2 0 0 1 2-2h5.5zm-3 0A1.5 1.5 0 0 1 9.5 3V1H4a1 1 0 0 0-1 1v12a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1V4.5z" />
      </svg>
      <span>JavaScript</span>
    </button>
  </div>

  <button
    type="button"
    bsCombobox
    placeholder="Select a role…"
    aria-label="Role"
    [menu]="roles"
    [(value)]="role"></button>
  <div bsComboboxMenu check #roles="bsComboboxMenu">
    <button type="button" bsComboboxOption value="admin">
      <span class="menu-item-content">
        <span>Admin</span>
        <small class="menu-item-description">Full access to all resources</small>
      </span>
    </button>
    <button type="button" bsComboboxOption value="editor">
      <span class="menu-item-content">
        <span>Editor</span>
        <small class="menu-item-description">Can edit and publish content</small>
      </span>
    </button>
    <button type="button" bsComboboxOption value="viewer">
      <span class="menu-item-content">
        <span>Viewer</span>
        <small class="menu-item-description">Read-only access</small>
      </span>
    </button>
  </div>
</div>

Put a bsComboboxSearch input in a .combobox-search at the top of the menu to filter options by their text, ignoring case and accents. It gets focus when the menu opens, and ↓ moves to the options. Add a bsComboboxNoResults message for when nothing matches.

<button
  type="button"
  bsCombobox
  placeholder="Select a country…"
  aria-label="Country"
  [menu]="countries"
  [(value)]="country"></button>
<div bsComboboxMenu #countries="bsComboboxMenu">
  <div class="combobox-search">
    <input bsComboboxSearch placeholder="Search…" aria-label="Search countries" />
  </div>
  <button type="button" bsComboboxOption value="us">United States</button>
  <button type="button" bsComboboxOption value="uk">United Kingdom</button>
  <button type="button" bsComboboxOption value="ca">Canada</button>
  <button type="button" bsComboboxOption value="au">Australia</button>
  <button type="button" bsComboboxOption value="de">Germany</button>
  <button type="button" bsComboboxOption value="fr">France</button>
  <button type="button" bsComboboxOption value="jp">Japan</button>
  <button type="button" bsComboboxOption value="br">Brazil</button>
  <button type="button" bsComboboxOption value="in">India</button>
  <button type="button" bsComboboxOption value="mx">Mexico</button>
  <div bsComboboxNoResults>No results found</div>
</div>

Groups

Label groups of options with .menu-header elements.

<button
  type="button"
  bsCombobox
  placeholder="Select a language…"
  aria-label="Programming language"
  [menu]="languages"
  [(value)]="language"></button>
<div bsComboboxMenu #languages="bsComboboxMenu">
  <div class="menu-header" role="presentation">Frontend</div>
  <button type="button" bsComboboxOption value="html">HTML</button>
  <button type="button" bsComboboxOption value="css">CSS</button>
  <button type="button" bsComboboxOption value="js">JavaScript</button>
  <div class="menu-header" role="presentation">Backend</div>
  <button type="button" bsComboboxOption value="python">Python</button>
  <button type="button" bsComboboxOption value="ruby">Ruby</button>
  <button type="button" bsComboboxOption value="go">Go</button>
</div>

Multiple select

Set multiple to select several options. The value is an array, the menu stays open while you pick, and the button shows the count when more than one is selected. Change that text with countText.

Value: css

<button
  type="button"
  bsCombobox
  multiple
  placeholder="Select skills…"
  aria-label="Skills"
  [menu]="skillMenu"
  [(value)]="skills"></button>
<div bsComboboxMenu #skillMenu="bsComboboxMenu">
  <button type="button" bsComboboxOption value="html">HTML</button>
  <button type="button" bsComboboxOption value="css">CSS</button>
  <button type="button" bsComboboxOption value="js">JavaScript</button>
  <button type="button" bsComboboxOption value="ts">TypeScript</button>
  <button type="button" bsComboboxOption value="angular">Angular</button>
</div>
<p class="mt-3 mb-0 fg-3">Value: {{ skills() }}</p>

Sizing

Set size to sm or lg to match form control sizes.

HTML

<div class="vstack gap-3 align-items-start">
  <button
    type="button"
    bsCombobox
    size="sm"
    placeholder="Small combobox"
    aria-label="Small combobox"
    [menu]="small"></button>
  <div bsComboboxMenu #small="bsComboboxMenu">
    <button type="button" bsComboboxOption value="1">One</button>
    <button type="button" bsComboboxOption value="2">Two</button>
  </div>
  <button
    type="button"
    bsCombobox
    placeholder="Default combobox"
    aria-label="Default combobox"
    [menu]="medium"></button>
  <div bsComboboxMenu #medium="bsComboboxMenu">
    <button type="button" bsComboboxOption value="1">One</button>
    <button type="button" bsComboboxOption value="2">Two</button>
  </div>
  <button
    type="button"
    bsCombobox
    size="lg"
    placeholder="Large combobox"
    aria-label="Large combobox"
    [menu]="large"></button>
  <div bsComboboxMenu #large="bsComboboxMenu">
    <button type="button" bsComboboxOption value="1">One</button>
    <button type="button" bsComboboxOption value="2">Two</button>
  </div>
</div>

Disabled

Disable the whole combobox with disabled or its form control, or single options with disabled on the option.

HTML

<div class="d-flex flex-wrap gap-3">
  <button
    type="button"
    bsCombobox
    disabled
    placeholder="Disabled combobox"
    aria-label="Disabled combobox"
    [menu]="off"></button>
  <div bsComboboxMenu #off="bsComboboxMenu">
    <button type="button" bsComboboxOption value="1">One</button>
  </div>
  <button
    type="button"
    bsCombobox
    placeholder="Some options disabled"
    aria-label="Combobox with disabled options"
    [menu]="some"></button>
  <div bsComboboxMenu #some="bsComboboxMenu">
    <button type="button" bsComboboxOption value="1">Available</button>
    <button type="button" bsComboboxOption value="2" disabled>Sold out</button>
    <button type="button" bsComboboxOption value="3">Available too</button>
  </div>
</div>

Form submission

Set name to submit the value with a native form: the combobox renders a hidden input, with values joined by commas when multiple.

HTML

<form class="d-flex gap-2" action="about:blank" target="_blank">
  <button
    type="button"
    bsCombobox
    name="size"
    placeholder="Choose a size…"
    aria-label="Size"
    [menu]="sizes"></button>
  <div bsComboboxMenu #sizes="bsComboboxMenu">
    <button type="button" bsComboboxOption value="s">Small</button>
    <button type="button" bsComboboxOption value="m">Medium</button>
    <button type="button" bsComboboxOption value="l">Large</button>
  </div>
  <button type="submit" bsButton theme="primary">Submit</button>
</form>

API

BsCombobox

Selector: button[bsCombobox] · Exported as: bsCombobox

Inputs

Name	Type	Default	Description
`menu`	`BsComboboxMenu`		The menu of options. Required.
`value`	`unknown`	`null`	Selected option value, or an array with multiple. Supports [(value)].
`multiple`	`boolean`	`false`	Selects several options.
`placeholder`	`string`	`''`	Text shown when nothing is selected.
`name`	`string \| null`	`null`	Name of a hidden input that submits the value with a native form.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Size of the button.
`compareWith`	`(a, b) => boolean`	`Object.is`	Compares option values with the value.
`countText`	`(count: number) => string`	`${count} selected`	Text shown when several options are selected.
`disabled`	`boolean`	`false`	Disables the control. Forms also disable it through the form control.
`id`	`string`	`generated`	Element id. Generated when not set, and used for the field’s label.
`validation`	`'auto' \| 'valid' \| 'invalid' \| 'none'`	`'auto'`	Validation styles. auto follows the bound Angular form control.

Outputs

Name	Type	Description
`valueChange`	`unknown`	Emits the value when the user selects an option.

Methods

Name	Type	Description
`select(value)`	`void`	Selects an option, or toggles it with multiple.
`isSelected(value)`	`boolean`	Whether a value is selected.
`show() / hide() / toggle()`	`void`	Opens or closes the menu.

BsComboboxMenu

Selector: [bsComboboxMenu] · Exported as: bsComboboxMenu

Inputs

Name	Type	Default	Description
`check`	`boolean`	`false`	Shows check marks on selected options. Always on with multiple.
`placement`	`BsPlacement`	`'bottom-start'`	Where the menu opens.

BsComboboxOption

Selector: button[bsComboboxOption] · Exported as: bsComboboxOption

Inputs

Name	Type	Default	Description
`value`	`unknown`		Value of the option. Required.
`label`	`string \| undefined`	`undefined`	Text shown in the combobox when selected. Defaults to the first .menu-item-content span, or the text.
`disabled`	`boolean`	`false`	Disables the option.

BsComboboxSearch

Selector: input[bsComboboxSearch]

BsComboboxNoResults

Selector: [bsComboboxNoResults]

Search the docs

Combobox

Example

With form field

Custom content

Search menu items

Groups

Multiple select

Sizing

Disabled

Form submission

API

BsCombobox

Inputs

Outputs

Methods

BsComboboxMenu

Inputs

BsComboboxOption

Inputs

BsComboboxSearch

BsComboboxNoResults