OOUI/Widgets/Selects and Options

Any widget that provides mutually exclusive options should be built using a SelectWidget that contains instances of OptionWidget (e.g., a ButtonSelectWidget that contains ButtonOptionWidgets, a RadioSelectWidget that contains RadioOptionWidgets, or a MenuSelectWidget that contains MenuOptionWidgets).

OptionWidgets are special elements that can be selected and (optionally, though almost always) configured with data, which can be a string, object, or number. The data is often unique for each option, but it does not have to be. A widget used to select a city by ZIP code, for example, might have labeled options with the different numerical codes, but the same data value (e.g., ‘San Francisco’) for all codes that belong to that city.

Note that if an OptionWidget is added to a SelectWidget that already contains an option with the same reference, the existing option will be removed, and the new option will be added to the end of the option array.

SelectWidgets emit several types of events that have subtle but important differences: SelectWidgets have a number of useful methods for finding items as well as getting and changing their state. In general, all modifications to the highlight or selection should be handled by the SelectWidget rather than by its individual options (e.g., use the SelectWidget’s highlightItem method to set a highlighted option, not the option-level method).
 * highlight indicates which item may be selected when a user presses enter or clicks. When a user mouses over an item, it is highlighted.
 * press is a state that occurs when a user mouses down on an item, but has not yet let go of the mouse. The item may appear selected, but it will not be selected until the user releases the mouse. ‘press’ can be used to give feedback to a user between mousedown and mouseup.
 * choose is something that happens only when the user makes a selection. Choose is never modified programmatically. If a user chooses an item, it becomes selected. You might wish to use this event if you wish to close a menu when a user chooses an item.
 * select changes which item is currently selected. A select can be made programmatically or by a user (i.e., the user chooses an item and the item is then selected).

For a full list of supported methods and configuration options, please see the code-level documentation.

Button selects and options
The following example demonstrates how to create and configure a ButtonSelectWidget that contains three options. Note that the ButtonOptionWidgets are created, but are not appended to the DOM. Instead, they are added to the ButtonSelect using the ButtonSelectWidget’s items configuration option. For a full list of supported methods and configuration options, please see the code-level documentation.

Radio selects and options
The following example illustrates a RadioSelectWidget that contains two radio options. Note that the first option has been selected using the RadioSelectWidget’s selectItem method. For a full list of supported methods and configuration options, please see the code-level documentation.

Menu selects and options
The OOjs UI library contains two types of ready-to-use widgets that contain menus: DropdownWidgets and ComboBoxWidgets. Note that MenuSelectWidgets themselves are not designed to be instantiated directly, rather subclassed and customized to be opened, closed, and displayed as needed. See ‘Extending the library’ for more information.

By default, menus are clipped to the visible viewport and the toggle value is set to ‘false’ (i.e., the menu is not visible) when a user presses the mouse outside the menu.

Menus also have support for keyboard interaction:
 * Enter/Return key: choose and select a menu option
 * Up-arrow key: highlight the previous menu option
 * Down-arrow key: highlight the next menu option
 * Esc key: hide the menu

Dropdown menus
DropdownWidgets are not menus themselves, rather they contain a menu, which can be accessed with the getMenu method. The DropdownWidget takes care of opening and displaying the menu so that users can interact with it.

To create a dropdown menu, use a DropdownWidget that contains a menu of options: DropdownWidgets can be configured with icons, indicators, labels, and titles. By default, the widget will use a ‘down’ indicator. The class defines one public method, getMenu: For a complete list of supported configuration options and methods, please see the code-level documentation for DropdownWidget.

ComboBox menus
ComboBoxWidgets combine a text input field (where a value can be entered manually) and a menu of options (from which a value can be chosen instead). Users can choose options from the combobox in one of two ways: To create a combobox with options populated by the server, which might be useful if you’d like to narrow down a long static list of options based on the characters the user types, use the LookupInputWidget mixin. Please see ‘Extending the Library’ for more information.
 * 1) By typing a value in the text input field. If the value exactly matches the value of a menu option, that option will appear to be selected.
 * 2) By choosing a value from the menu. The value of the chosen option will then appear in the text input field.

To create a combobox widget use a ComboBoxWidget with a menu of options: ComboBoxWidgets can be disabled or configured with CSS and initial values for the text input and menu options. For a complete list of supported configuration options and methods, please see the code-level documentation.