---
layout: doc
title: deliteful/Combobox
---
# deliteful/Combobox
`deliteful/Combobox` is a form-aware and store-aware widget leveraging the
[`deliteful/list/List`](./list/List.md) widget for
displaying the list of options.
Main features:
* Allows to benefit from the customization mechanism of the list item rendering.
* Provides single and multiple selection modes.
* Provides optional interactive filtering of list of options (single selection mode only).
* Multichannel rendering.
*Example of deliteful/Combobox (single choice mode, on desktop browser):*
*Example of deliteful/Combobox (multiple choice mode, on mobile browser):*
##### Table of Contents
[Element Instantiation ](#instantiation)
[Using Combobox](#using)
[Element Styling](#styling)
[Enterprise Use](#enterprise)
## Element Instantiation
For details on the instantiation lifecycle, see [`delite/Widget`](/delite/docs/master/Widget.md).
### Declarative Instantiation
```js
require(["delite/register", "deliteful/Store",
"deliteful/Combobox", "requirejs-domready/domReady!"],
function (register) {
register.parse();
});
```
```html
{ "label": "France", ... },
...
```
### Programmatic Instantiation
```js
require(["delite/register", "dstore/Memory", "dstore/Trackable",
"deliteful/Combobox", "deliteful/list/List",
"requirejs-domready/domReady!"],
function (register, Memory, Trackable, Combobox, List) {
register.parse();
// Create the store
var dataStore = new (Memory.createSubclass(Trackable))({});
// Add options
dataStore.add(...);
...
// Create the List
var list = new List({store: dataStore, ...});
// Create the Combobox
var Combobox = new Combobox({list: list, selectionMode: "multiple"});
Combobox.placeAt(document.body);
});
```
Note that the `list` property is set by default to a newly created instance of
`deliteful/list/List`. Hence, applications can write:
```js
var combobox = new Combobox();
// Create the store
combobox.list.store = ...;
...
```
## Using Combobox
### Selection
The widget provides two selection modes through the `selectionMode` property:
"single" (only one option can be selected at a time) and "multiple" (one or more
options can be selected).
Options can be selected programmatically using the `selectedItem` property (or, for multiple
selection mode, `selectedItems`) inherited from [`delite/Selection`](/delite/docs/master/Selection.md).
### Auto Filtering
In single selection mode, if the property `autoFilter` is set to `true` (default is `false`)
the widget allows to type one or more characters which are used for filtering
the list of shown list items. By default, the filtering is case-insensitive, and an item
is shown if its label contains the entered string.
The default filtering policy can be customized using the `filterMode` and
`ignoreCase` properties.
The valid values of `filterMode` are:
* `"startsWith"`: the item matches if its label starts with the filter text.
* `"contains"`: the item matches if its label contains the filter text.
* `"is"`: the item matches if its label is the filter text.
The matching is case insensitive by default. Setting `ignoreCase` to `false` turns
it case sensitive.
The filtering is performed by the `filter(fitlerTxt)` method, which is called automatically
while the user types into the editable input element, with `filterTxt` being the currently
entered text. The default implementation of this method uses `dstore/Filter.match()`.
The matching is performed against the `list.labelAttr` attribute of the data store items.
The method can be overridden for implementing other filtering strategies.
### Attribute Mapping
The customization of the mapping of data store item attributes into render item attributes
can be done on the List instance using the mapping API of
[`deliteful/list/List`](./list/List.md), as supported by its superclass
`delite/StoreMap`.
See the [`delite/StoreMap`](/delite/docs/master/StoreMap.md) documentation for
more information about the available mapping options, and the section
[`Store capabilities`](./list/List.md#store) of List's documentation.
### Multichannel rendering
The widget provides multichannel rendering: the popup is displayed on
large screens (desktop-like) below/above the main element, while on small and medium
screens (phone-like and tablet-like), to optimize the usage of the available space,
the popup is displayed in a centered overlay (an instance of `deliteful/Combobox/ComboPopup`
is used in this case).
The channel is controlled by the value of the `has()` channel flags set by
`deliteful/features` using CSS media queries depending on the screen size.
See the [`deliteful/features`](./features.md) documentation
for information about how to configure the channel. Also, see the
[`deliteful/channelBreakpoints`](./channelBreakpoints.md) documentation for information
about how to customize the values of the screen size breakpoints used by the media queries.
### Value and form support
The widget supports the following form-related properties: `value`, `name`, `disabled`
and `alt`, inherited from [`delite/FormWidget`](/delite/docs/master/FormWidget.md), and
`readOnly` inherited from [`delite/FormValueWidget`](/delite/docs/master/FormValueWidget.md).
The `value` property of the widget contains:
* Single selection mode: the value of the selected list items. By default, the
value of the first item is selected.
* Multiple selection mode: an array containing the values of the selected items.
Defaults to `[]`.
If the widget is used in an HTML form, the submitted value contains:
* Single selection mode: the same as widget's `value` property.
* Multiple selection mode: a string containing a comma-separated list of the values
of the selected items. Defaults to `""`.
By default, the `label` field of the List's render items is used as value of the item.
If the value needs to be different than the label, an attribute mapping needs to be
set for `value` on the `List` instance, for example:
```js
// Create the store
var dataStoreWithValue = new Memory({idProperty: "label",
data: [
{ label: "France", value: "FR" },
{ label: "Germany", value: "DE" },
...
]});
// Create the List and set valueAttr to specify the name of the field
// which stores the value of the item (valueFunc can also be used
// for dynamically computed values)
var list = new List({store: dataStoreWithValue, valueAttr: "value", ...});
// Create the Combobox
var combobox = new Combobox({list: list, ...});
combobox.placeAt(document.body);
```
or in markup:
```html
{ "label": "France", "value": "FR" },
...
```
If no mapping is specified for `value`, the item label is used as value (itself subject to
attribute mapping using `List.labelAttr` or `List.labelFunc`).
## Element Styling
### Supported themes
This widget provides default styling for the following delite theme:
* bootstrap
### CSS Classes
CSS classes are bound to the structure of the widget declared in its template `deliteful/Combobox/Combobox.html`.
The following table lists the CSS classes that can be used to style the Combobox widget.
|Class name/selector|Applies to|
|----------|----------|
|d-combobox|Combobox widget root node.
|d-combobox-input|The native `` nodes used by the Combobox widget.
|d-combobox-list|The List widget displayed inside the popup.
|d-combo-ok-button|The OK button used in some cases inside the popup.
|d-combo-cancel-button|The Cancel button used in some cases inside the popup.
## Enterprise Use
### Accessibility
|type|status|comment|
|----|------|-------|
|Keyboard|ok|For details, see below this table.|
|Visual Formatting|ok|Tested for high constrast and browser zoom (200%), in IE and Firefox.|
|Screen Reader|ok|Tested on JAWS 15 and iOS VoiceOver.|
Keyboard navigation details:
* DOWN arrow opens the focused combobox.
* In single selection mode:
* UP and DOWN arrows select the next, respectively the previous option.
* RETURN and ESCAPE validate the change.
* In multiple selection mode:
* UP and DOWN arrows navigate to the next, respectively the previous option.
* SPACE toggles the selected state of the currently navigated option.
* RETURN and ESCAPE validate the change.
### Globalization
`deliteful/Combobox` provides an internationalizable bundle that contains the following
messages:
|Key|Role|
|----------|----------|
|"multiple-choice"|Text written in the combo in multiple selection mode if more than one item is selected.
|"multiple-choice-no-selection"|Text written in the combo in multiple selection mode if no item is selected.
|"search-placeholder"|Set as placeholder attribute of the input element used for filtering the list of options.
|"ok-button-label"|The label of the OK button used for multiple selection mode on mobile.
|"cancel-button-label"|The label of the Cancel button used for multiple selection mode on mobile.
The first 3 strings in the table above are used as default values for the widget properties
`multipleChoiceMsg`, `multipleChoiceNoSelectionMsg`, and respectively `searchPlaceHolder`.
To customize these strings on a per-widget basis, set directly these properties.
Right to left orientation is supported by setting the `dir` attribute to `rtl` on the
widget.
### Security
This class has no specific security concern.
### Browser Support
This class supports all supported browsers.