How to use the ComboBox component

The ComboBox class displays an editable text input and a button, that when triggered, renders the items from a data collection in a pop-up list view.

⚠️ Beta Notice: This component is still quite new to Feathers UI. It was included in the latest release because it should be stable enough for production use. However, some APIs may go through minor changes in upcoming releases — based on feedback from developers like you. Learn more about Beta APIs.

The Basics

Start by creating a ComboBox control, and add it to the display list.

var comboBox = new ComboBox();
addChild(comboBox);

Data provider

To render some data in the combo box, pass in a collection that contains an object for each row.

comboBox.dataProvider = new ArrayCollection([
    { text: "A" },
    { text: "B" },
    { text: "C" }
]);

Set the itemToText() method to get the text from each item to display in an item renderer.

comboBox.itemToText = function(item:Dynamic):String {
    return item.text;
};

Items in the collection are not required to be simple object literals, like in the example above. Instances of a class are allowed too (and encouraged as a best practice).

Add an event listener for Event.CHANGE to perform an action when the user selects a different item.

comboBox.addEventListener(Event.CHANGE, comboBox_changeHandler);

Check for the new value of the selectedItem property in the listener.

function comboBox_changeHandler(event:Event):Void {
    var comboBox = cast(event.currentTarget, ComboBox);
    trace("ComboBox selectedItem change: " + comboBox.selectedItem.text);
}

Alternatively, the value of the selectedIndex property references the index of the items in the combo box's collection, in the order that they were added.

function comboBox_changeHandler(event:Event):Void {
    var comboBox = cast(event.currentTarget, ComboBox);
    trace("ComboBox selectedIndex change: " + comboBox.selectedIndex);
}

Add or remove items

To add a new item at the end, pass an object to the data provider's add() method.

var newItem = { text: "New Item" };
comboBox.dataProvider.add(newItem);

To add a new item at a specific position, pass an object to the data provider's addAt() method.

var newItem = { text: "First Item" };
comboBox.dataProvider.addAt(newItem, 0);

In the example above, a new item is added to the beginning.

Similarly, to remove an item, call remove() or removeAt() on the collection.

comboBox.dataProvider.removeAt(0);

Styles

A number of styles may be customized on the sub-components of a ComboBox component, including styles on the button, the text input, and the list view.

Button

The button in a ComboBox component is of type Button. Its appearance may be customized globally in a theme, or it may be customized outside of a theme on an specific, individual ComboBox.

See How to use the Button component for complete details about which styles are available for the button.

Style button globally

Use the ComboBox.CHILD_VARIANT_BUTTON constant in a theme to provide a function that globally styles the buttons in all ComboBox components.

styleProvider.setStyleFunction(
    Button,
    ComboBox.CHILD_VARIANT_BUTTON,
    setComboBox_Button_Styles);

The function should use the following signature.

function setComboBox_Button_Styles(button:Button):Void {
    // ... set styles here
}

Style the button in a specific ComboBox

The buttonFactory property may be used to customize the creation of an individual button.

comboBox.buttonFactory = () -> {
    var button = new Button();
    // ... set styles here
    return button;
};

TextInput

The text input in a ComboBox component is of type TextInput. Its appearance may be customized globally in a theme, or it may be customized outside of a theme on an specific, individual ComboBox.

See How to use the TextInput component for complete details about which styles are available for the text input.

Style text input globally

Use the ComboBox.CHILD_VARIANT_TEXT_INPUT constant in a theme to provide a function that globally styles the text inputs in all ComboBox components.

styleProvider.setStyleFunction(
    TextInput,
    ComboBox.CHILD_VARIANT_TEXT_INPUT,
    setComboBox_TextInput_Styles);

The function should use the following signature.

function setComboBox_TextInput_Styles(button:TextInput):Void {
    // ... set styles here
}

Style the text input in a specific ComboBox

The textInputFactory property may be used to customize the creation of an individual text input.

comboBox.textInputFactory = () -> {
    var input = new TextInput();
    // ... set styles here
    return input;
};

ListView

The list view in a ComboBox component is of type ListView. Its appearance may be customized globally in a theme, or it may be customized outside of a theme on an specific, individual ComboBox.

See How to use the ListView component for complete details about which styles are available for the list view.

Style list view globally

Use the ComboBox.CHILD_VARIANT_LIST_VIEW constant in a theme to provide a function that globally styles the list views in all ComboBox components.

styleProvider.setStyleFunction(
    ListView,
    ComboBox.CHILD_VARIANT_LIST_VIEW,
    setComboBox_ListView_Styles);

The function should use the following signature.

function setComboBox_ListView_Styles(button:ListView):Void {
    // ... set styles here
}

Style the list view in a specific ComboBox

The listViewFactory property may be used to customize the creation of an individual list view.

comboBox.listViewFactory = () -> {
    var listView = new ListView();
    // ... set styles here
    return listView;
};

Related Links

• feathers.controls.ComboBox API Documentation