carbon-components-svelte/docs/src/pages/components/ComboBox.svx

<script>
  import { ComboBox, InlineNotification } from "carbon-components-svelte";
  import Preview from "../../components/Preview.svelte";
</script>

`ComboBox` combines a text input with a dropdown menu to let users select from predefined options or enter custom values. It supports filtering, custom item rendering, and various states.

`ComboBox` is keyed for performance reasons.

<InlineNotification svx-ignore lowContrast title="Note:" kind="info" hideCloseButton>
  <div class="body-short-01">Every <code>items</code> object must have a unique "id" property.</div>
</InlineNotification>

## Default

Create a combobox with a title and placeholder text. Each item requires a unique `id` and `text`.

<ComboBox titleText="Contact" placeholder="Select contact method"
items={[
  {id: "0", text: "Slack"},
  {id: "1", text: "Email"},
  {id: "2", text: "Fax"}
  ]}  />

## Custom slot

Override the default slot to customize how each item displays. Access the item and index through the `let:` directive.

<FileSource src="/framed/ComboBox/ComboBoxSlot" />

## Hidden label

Set `hideLabel` to `true` to visually hide the label while keeping it accessible to screen readers.

<ComboBox hideLabel titleText="Hidden Label" placeholder="Select contact method"
items={[
  {id: "0", text: "Slack"},
  {id: "1", text: "Email"},
  {id: "2", text: "Fax"}
  ]}  />

## Initial selected id

Set `selectedId` to pre-select an item when the combobox loads.

<ComboBox titleText="Contact" placeholder="Select contact method"
selectedId="1"
items={[
  {id: "0", text: "Slack"},
  {id: "1", text: "Email"},
  {id: "2", text: "Fax"}
  ]}  />

## Reactive example

See how the combobox responds to user input and selection changes.

<FileSource src="/framed/ComboBox/ReactiveComboBox" />

## Clear selection

Use `bind:this` to access the component instance and call `ComboBox.clear()` to programmatically clear the selection.

Set `focus: false` in the method options to prevent re-focusing the input.

<FileSource src="/framed/ComboBox/ComboBoxClear" />

## Multiple combo boxes

See how to manage multiple comboboxes in a form.

<FileSource src="/framed/ComboBox/MultipleComboBox" />

## Filterable

Enable filtering to let users search through the options.

<FileSource src="/framed/ComboBox/FilterableComboBox" />

## Filterable with custom label

Set `itemToString` to customize how items display in the filterable combobox.

<FileSource src="/framed/ComboBox/FilterableComboBoxCustomLabel" />

## Top direction

Set `direction` to `"top"` to make the dropdown menu appear above the input.

<ComboBox direction="top" titleText="Contact" placeholder="Select contact method"
items={[
  {id: "0", text: "Slack"},
  {id: "1", text: "Email"},
  {id: "2", text: "Fax"}
  ]}  />

## Light variant

Set `light` to `true` to use the light color scheme.

<ComboBox light titleText="Contact" placeholder="Select contact method"
items={[
  {id: "0", text: "Slack"},
  {id: "1", text: "Email"},
  {id: "2", text: "Fax"}
  ]}  />

## Extra-large size

Set `size` to `"xl"` for an extra-large combobox.

<ComboBox titleText="Contact" placeholder="Select contact method"
size="xl"
items={[
  {id: "0", text: "Slack"},
  {id: "1", text: "Email"},
  {id: "2", text: "Fax"}
  ]}  />

## Small size

Set `size` to `"sm"` for a small combobox.

<ComboBox titleText="Contact" placeholder="Select contact method"
size="sm"
items={[
  {id: "0", text: "Slack"},
  {id: "1", text: "Email"},
  {id: "2", text: "Fax"}
  ]}  />

## Invalid state

Set `invalid` to `true` and provide `invalidText` to show an error message.

<ComboBox invalid invalidText="Secondary contact method must be different from the primary contact" titleText="Contact" placeholder="Select contact method"
items={[
  {id: "0", text: "Slack"},
  {id: "1", text: "Email"},
  {id: "2", text: "Fax"}
  ]}  />

## Warning state

Set `warn` to `true` and provide `warnText` to show a warning message.

<ComboBox warn warnText="This contact method is not associated with your account" titleText="Contact" placeholder="Select contact method"
items={[
  {id: "0", text: "Slack"},
  {id: "1", text: "Email"},
  {id: "2", text: "Fax"}
  ]}  />

## Disabled state

Set `disabled` to `true` to prevent interaction with the combobox.

<ComboBox disabled titleText="Contact" placeholder="Select contact method"
items={[
  {id: "0", text: "Slack"},
  {id: "1", text: "Email"},
  {id: "2", text: "Fax"}
  ]}  />

## Disabled items

Set `disabled: true` in an item object to disable specific options.

<ComboBox
  titleText="Contact"
  placeholder="Select contact method"
  items={[
    { id: "0", text: "Slack" },
    { id: "1", text: "Email", disabled: true },
    { id: "2", text: "Fax" },
  ]}
/>