OOUI/Widgets/Selects and Options

Any widget that provides mutually exclusive options should be built using a  that contains instances of   (e.g., a   that contains , a   that contains  , or a   that contains  ).

s are special elements that can be selected and (optionally, though almost always) configured with, 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  is added to a   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.

s emit several types of events that have subtle but important differences: s 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  rather than by its individual options (e.g., use the  ’s   method to set a highlighted option, not the option-level method).
 * indicates which item may be selected when a user presses enter or clicks. When a user mouses over an item, it is highlighted.
 * 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.  can be used to give feedback to a user between mousedown and mouseup.
 * 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.
 * 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   that contains three options. Note that the  s are created, but are not appended to the DOM. Instead, they are added to the  using the  ’s   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  that contains two radio options. Note that the first option has been selected using the ’s   method.



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

Menu selects and options
The OOUI library contains two types of ready-to-use widgets that contain menus:  s and  s. Note that MenuSelectWidgets themselves are not designed to be instantiated directly, rather subclassed and customized to be opened, closed, and displayed as needed.

By default, menus are clipped to the visible viewport and the toggle value is set to  (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

Note that there is also an OOUI MenuLayout, which is a two-panel layout that does not by default contain a MenuSelectWidget (but it can be used with one).

Dropdown menus
 s are not menus themselves, rather they contain a menu, which can be accessed with the  method. The  takes care of opening and displaying the menu so that users can interact with it. If you would like to use a dropdown in an HTML form, use  instead.

The menu can be placed inside an overlay to avoid being clipped by outer elements. See OOUI/Concepts for details.

To create a dropdown menu, use a  that contains a menu of options:

s can be configured with icons, indicators, labels, and titles. By default, the widget will use a ‘down’ indicator. The class defines one public method, :

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

ComboBox menus
 s 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 LookupElement mixin. Please see OOjs/Inheritance 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:

s 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.