Expand all

OO.ui.MenuSelectWidget

Extends

Constructor

MenuSelectWidget is a select widget that contains options and is used together with OO.ui.MenuOptionWidget. It is designed be used as part of another widget. See DropdownWidget, ComboBoxInputWidget, and LookupElement for examples of widgets that contain menus. MenuSelectWidgets themselves are not instantiated directly, rather subclassed and customized to be opened, closed, and displayed as needed.

By default, menus are clipped to the visible viewport and are 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
  • Escape key: hide the menu

Unlike most widgets, MenuSelectWidget is initially hidden and must be shown by calling #toggle.

Please see the [OOUI documentation on MediaWiki][1] for more information. [1]: https://www.mediawiki.org/wiki/OOUI/Widgets/Selects_and_Options

Parameters:

Name Type Attributes Description
config Object optional

Configuration options

Properties:
Name Type Attributes Default Description
input OO.ui.TextInputWidget optional

Text input used to implement option highlighting for menu items that match the text the user types. This config is used by ComboBoxInputWidget and LookupElement
$input jQuery optional

Text input used to implement option highlighting for menu items that match the text the user types. This config is used by TagMultiselectWidget
widget OO.ui.Widget optional

Widget associated with the menu's active state. If the user clicks the mouse anywhere on the page outside of this widget, the menu is hidden. For example, if there is a button that toggles the menu's visibility on click, the menu will be hidden then re-shown when the user clicks that button, unless the button (or its parent widget) is passed in here.
autoHide boolean optional
 true

Hide the menu when the mouse is pressed outside the menu.
$autoCloseIgnore jQuery optional

If these elements are clicked, don't auto-hide the menu.
hideOnChoose boolean optional
 true

Hide the menu when the user chooses an option.
filterFromInput boolean optional
 false

Filter the displayed options from the input
highlightOnFilter boolean optional
 false

Highlight the first result when filtering
filterMode string optional
 'prefix'

The mode by which the menu filters the results. Options are 'exact', 'prefix' or 'substring'. See OO.ui.SelectWidget#getItemMatcher
width number | string optional

Width of the menu as a number of pixels or CSS string with unit suffix, used by ClippableElement
Mixes in:
Source:

MenuSelectWidget is a select widget that contains options and is used together with OO.ui.MenuOptionWidget.

Properties

flippedPositionsstatic #

Positions to flip to if there isn't room in the container for the menu in a specific direction.

Properties:

Type Description
Object.<string, string>
Source:

Positions to flip to if there isn't room in the container for the menu in a specific direction.

Methods

addItems([items], [index]) → {OO.ui.Widget}chainable #

Add an array of options to the select. Optionally, an index number can be used to specify an insertion point.

Parameters:

Name Type Attributes Description
items Array.<OO.ui.OptionWidget> optional

Options to add
index number optional

Index to insert items after
Overrides:
Source:

Fires:

Returns:

The widget, for chaining

Type
OO.ui.Widget
Add an array of options to the select.

bindDocumentKeyDownListener()protected #

Bind document key down listener.

Overrides:
Source:
Bind document key down listener.

bindDocumentKeyPressListener()protected #

Bind document key press listener.

Overrides:
Source:
Bind document key press listener.

chooseItem(item) → {OO.ui.Widget}chainable #

Select an item or toggle an item's selection when multiselect is enabled.

When a user chooses an item, the menu is closed, unless the hideOnChoose config option is set to false.

Note that ‘choose’ should never be modified programmatically. A user can choose an option with the keyboard or mouse and it becomes selected. To select an item programmatically, use the #selectItem method.

Parameters:

Name Type Description
item OO.ui.OptionWidget

Item to choose
Overrides:
Source:

Returns:

The widget, for chaining

Type
OO.ui.Widget
Select an item or toggle an item's selection when multiselect is enabled.

clearItems() → {OO.ui.Widget}chainable #

Clear all options from the select. Options will be detached from the DOM, not removed, so that they can be reused later. To remove a subset of options from the select, use the #removeItems method.

Overrides:
Source:

Fires:

Returns:

The widget, for chaining

Type
OO.ui.Widget
Clear all options from the select.

clearKeyPressBuffer()protected #

Clear the key-press buffer

Inherited from:
Source:
Clear the key-press buffer

findFirstSelectableItem() → {OO.ui.OptionWidget|null} #

Find the next selectable item or null if there are no selectable items. Disabled options and menu-section markers and breaks are not selectable.

Inherited from:
Source:

Returns:

Item, null if there aren't any selectable items

Type
OO.ui.OptionWidget | null
Find the next selectable item or null if there are no selectable items.

findFirstSelectedItem() → {OO.ui.OptionWidget|null} #

Inherited from:
Source:

Returns:

The first (of possibly many) selected item, if any

Type
OO.ui.OptionWidget | null

findHighlightedItem() → {OO.ui.OptionWidget|null} #

Find highlighted item.

Inherited from:
Source:

Returns:

Highlighted item, null if no item is highlighted

Type
OO.ui.OptionWidget | null
Find highlighted item.

findRelativeSelectableItem(item, offset, [filter], [wrap]) → {OO.ui.OptionWidget|null} #

Find an option by its position relative to the specified item (or to the start of the option array, if item is null). The direction and distance in which to search through the option array is specified with a number: e.g. -1 for the previous item (the default) or 1 for the next item, or 15 for the 15th next item, etc. The method will return an option, or null if there are no options in the array.

Parameters:

Name Type Attributes Default Description
item OO.ui.OptionWidget | null

Item to describe the start position, or null to start at the beginning of the array.
offset number

Relative position: negative to move backward, positive to move forward
filter function optional

Only consider items for which this function returns true. Function takes an OO.ui.OptionWidget and returns a boolean.
wrap boolean optional
 false

Do not wrap around after reaching the last or first item
Inherited from:
Source:

Returns:

Item at position, null if there are no items in the select

Type
OO.ui.OptionWidget | null

Find an option by its position relative to the specified item (or to the start of the option array, if item is null).

findSelectedItem() → {Array.<OO.ui.OptionWidget>|OO.ui.OptionWidget|null} #

Find selected item.

Inherited from:
Source:

Returns:

If the widget is multiselect then return an array of selected items (or empty array), if the widget is not multiselect, return a single selected item, or null if no item is selected

Type
Array.<OO.ui.OptionWidget> | OO.ui.OptionWidget | null
Find selected item.

findSelectedItems() → {Array.<OO.ui.OptionWidget>|OO.ui.OptionWidget|null} #

Find all selected items, if there are any. If the widget allows for multiselect it will return an array of selected options. If the widget doesn't allow for multiselect, it will return the selected option or null if no item is selected.

Inherited from:
Source:

Returns:

If the widget is multiselect then return an array of selected items (or empty array), if the widget is not multiselect, return a single selected item, or null if no item is selected

Type
Array.<OO.ui.OptionWidget> | OO.ui.OptionWidget | null
Find all selected items, if there are any.

getClosestScrollableElementContainer() → {HTMLElement} #

Get closest scrollable container.

Inherited from:
Source:

Returns:

Closest scrollable container

Type
HTMLElement
Get closest scrollable container.

getData() → {any} #

Get element data.

Inherited from:
Source:

Returns:

Element data

Type
any
Get element data.

getElementDocument() → {HTMLDocument} #

Get the DOM document.

Inherited from:
Source:

Returns:

Document object

Type
HTMLDocument
Get the DOM document.

getElementGroup() → {OO.ui.mixin.GroupElement|null} #

Get group element is in.

Inherited from:
Source:

Returns:

Group element, null if none

Type
OO.ui.mixin.GroupElement | null
Get group element is in.

getElementId() → {string} #

Ensure that the element has an 'id' attribute, setting it to an unique value if it's missing, and return its value.

Inherited from:
Source:

Returns:

Type
string

Ensure that the element has an 'id' attribute, setting it to an unique value if it's missing, and return its value.

getElementWindow() → {Window} #

Get the DOM window.

Inherited from:
Source:

Returns:

Window object

Type
Window
Get the DOM window.

getInputId() → {string|null} #

Get an ID of a labelable node which is part of this widget, if any, to be used for <label for> value.

If this function returns null, the widget should have a meaningful #simulateLabelClick method instead.

Inherited from:
Source:

Returns:

The ID of the labelable element

Type
string | null

Get an ID of a labelable node which is part of this widget, if any, to be used for <label for> value.

getItemFromLabel(label, [prefix]) → {OO.ui.Element|null} #

Fetch an item by its label.

Parameters:

Name Type Attributes Default Description
label string

Label of the item to select.
prefix boolean optional
 false

Allow a prefix match, if only a single item matches
Inherited from:
Source:

Returns:

Item with equivalent label, null if none exists

Type
OO.ui.Element | null
Fetch an item by its label.

getItemMatcher(query, [mode]) → {function}protected #

Get a matcher for the specific string

Parameters:

Name Type Attributes Default Description
query string

String to match against items
mode string optional
 'prefix'

Matching mode: 'substring', 'prefix', or 'exact'
Inherited from:
Source:

Returns:

function ( OO.ui.OptionWidget ) => boolean

Type
function
Get a matcher for the specific string

getTagName() → {string} #

Get the HTML tag name.

Override this method to base the result on instance information.

Inherited from:
Source:

Returns:

HTML tag name

Type
string
Get the HTML tag name.

getVisibleItems() → {Array.<OO.ui.MenuOptionWidget>} #

Return the visible items in the menu.

Source:

Returns:

Visible items

Type
Array.<OO.ui.MenuOptionWidget>
Return the visible items in the menu.

highlightItem([item]) → {OO.ui.Widget}chainable #

Highlight an option. If the item param is omitted, no options will be highlighted and any existing highlight will be removed. The highlight is mutually exclusive.

Parameters:

Name Type Attributes Description
item OO.ui.OptionWidget optional

Item to highlight, omit for no highlight
Inherited from:
Source:

Fires:

Returns:

The widget, for chaining

Type
OO.ui.Widget
Highlight an option.

isDisabled() → {boolean} #

Check if the widget is disabled.

Inherited from:
Source:

Returns:

Widget is disabled

Type
boolean
Check if the widget is disabled.

isElementAttached() → {boolean} #

Check if the element is attached to the DOM

Inherited from:
Source:

Returns:

The element is attached to the DOM

Type
boolean
Check if the element is attached to the DOM

isVisible() → {boolean} #

Check if element is visible.

Inherited from:
Source:

Returns:

element is visible

Type
boolean
Check if element is visible.

onDocumentKeyDown(e)protected #

Handle document key down events.

Parameters:

Name Type Description
e KeyboardEvent

Key down event
Overrides:
Source:
Handle document key down events.

onDocumentKeyPress(e) → {undefined|boolean}protected #

Handle key press events.

Parameters:

Name Type Description
e KeyboardEvent

Key press event
Inherited from:
Source:

Returns:

False to prevent default if event is handled

Type
undefined | boolean
Handle key press events.

onDocumentMouseDown(e)protected #

Handles document mouse down events.

Parameters:

Name Type Description
e MouseEvent

Mouse down event
Source:
Handles document mouse down events.

onToggle(visible)protected #

Visibility change handler

Parameters:

Name Type Description
visible boolean
Inherited from:
Source:
Visibility change handler

pressItem([item]) → {OO.ui.Widget}chainable #

Press an item.

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.

Parameters:

Name Type Attributes Description
item OO.ui.OptionWidget optional

Item to press, omit to depress all
Inherited from:
Source:

Fires:

Returns:

The widget, for chaining

Type
OO.ui.Widget
Press an item.

removeItems(items) → {OO.ui.Widget}chainable #

Remove the specified array of options from the select. Options will be detached from the DOM, not removed, so they can be reused later. To remove all options from the select, you may wish to use the #clearItems method instead.

Parameters:

Name Type Description
items Array.<OO.ui.OptionWidget>

Items to remove
Overrides:
Source:

Fires:

Returns:

The widget, for chaining

Type
OO.ui.Widget
Remove the specified array of options from the select.

restorePreInfuseState(state)protected #

Restore the pre-infusion dynamic state for this widget.

This method is called after #$element has been inserted into DOM. The parameter is the return value of #gatherPreInfuseState.

Parameters:

Name Type Description
state Object
Inherited from:
Source:
Restore the pre-infusion dynamic state for this widget.

scrollElementIntoView([config]) → {jQuery.Promise} #

Scroll element into view.

Parameters:

Name Type Attributes Description
config Object optional

Configuration options
Inherited from:
Source:

Returns:

Promise which resolves when the scroll is complete

Type
jQuery.Promise
Scroll element into view.

scrollItemIntoView(item) #

Scroll item into view, preventing spurious mouse highlight actions from happening.

Parameters:

Name Type Description
item OO.ui.OptionWidget

Item to scroll into view
Inherited from:
Source:
Scroll item into view, preventing spurious mouse highlight actions from happening.

scrollToTop() #

Scroll to the top of the menu

Source:
Scroll to the top of the menu

selectItem([item]) → {OO.ui.Widget}chainable #

Programmatically select an option by its reference. If the item parameter is omitted, all options will be deselected.

Parameters:

Name Type Attributes Description
item OO.ui.OptionWidget optional

Item to select, omit to deselect all
Inherited from:
Source:

Fires:

Returns:

The widget, for chaining

Type
OO.ui.Widget
Programmatically select an option by its reference.

selectItemByData([data]) → {OO.ui.Widget}chainable #

Programmatically select an option by its data. If the data parameter is omitted, or if the item does not exist, all options will be deselected.

Parameters:

Name Type Attributes Description
data Object | string optional

Value of the item to select, omit to deselect all
Inherited from:
Source:

Fires:

Returns:

The widget, for chaining

Type
OO.ui.Widget
Programmatically select an option by its data.

selectItemByLabel([label], [prefix]) → {OO.ui.Widget}chainable #

Programmatically select an option by its label. If the item does not exist, all options will be deselected.

Parameters:

Name Type Attributes Default Description
label string optional

Label of the item to select.
prefix boolean optional
 false

Allow a prefix match, if only a single item matches
Inherited from:
Source:

Fires:

Returns:

The widget, for chaining

Type
OO.ui.Widget
Programmatically select an option by its label.

setData(data) → {OO.ui.Element}chainable #

Set element data.

Parameters:

Name Type Description
data any

Element data
Inherited from:
Source:

Returns:

The element, for chaining

Type
OO.ui.Element
Set element data.

setDisabled([disabled]) → {OO.ui.Widget}chainable #

Set the 'disabled' state of the widget.

When a widget is disabled, it cannot be used and its appearance is updated to reflect this state.

Parameters:

Name Type Attributes Default Description
disabled boolean optional
 false

Disable widget
Inherited from:
Source:

Returns:

The widget, for chaining

Type
OO.ui.Widget
Set the 'disabled' state of the widget.

setElementGroup(group) → {OO.ui.Element}chainable #

Set group element is in.

Parameters:

Name Type Description
group OO.ui.mixin.GroupElement | null

Group element, null if none
Inherited from:
Source:

Returns:

The element, for chaining

Type
OO.ui.Element
Set group element is in.

setElementId(id) → {OO.ui.Element}chainable #

Set the element has an 'id' attribute.

Parameters:

Name Type Description
id string
Inherited from:
Source:

Returns:

The element, for chaining

Type
OO.ui.Element
Set the element has an 'id' attribute.

setFocusOwner($focusOwner)protected #

Set the DOM element which has focus while the user is interacting with this SelectWidget.

This is used to set aria-activedescendant and aria-expanded on it.

Parameters:

Name Type Description
$focusOwner jQuery
Inherited from:
Source:
Set the DOM element which has focus while the user is interacting with this SelectWidget.

setLabelledBy(id) #

Set the element with the given ID as a label for this widget.

Parameters:

Name Type Description
id string | null
Inherited from:
Source:
Set the element with the given ID as a label for this widget.

simulateLabelClick() #

Simulate the behavior of clicking on a label (a HTML <label> element) bound to this input. HTML only allows <label> to act on specific "labelable" elements; complex widgets might need to override this method to provide intuitive, accessible behavior.

By default, this does nothing. OO.ui.mixin.TabIndexedElement overrides it for focusable widgets. Individual widgets may override it too.

This method is called by OO.ui.LabelWidget and OO.ui.FieldLayout. It should not be called directly.

Inherited from:
Source:
Simulate the behavior of clicking on a label (a HTML <label> element) bound to this input.

supports(methods) → {boolean} #

Check if element supports one or more methods.

Parameters:

Name Type Description
methods string | Array.<string>

Method or list of methods to check
Inherited from:
Source:

Returns:

All methods are supported

Type
boolean
Check if element supports one or more methods.

toggle([show]) → {OO.ui.Element}chainable #

Toggle visibility of an element.

Parameters:

Name Type Attributes Description
show boolean optional

Make element visible, omit to toggle visibility
Overrides:
Source:

Fires:

Returns:

The element, for chaining

Type
OO.ui.Element
Toggle visibility of an element.

togglePressed([pressed]) #

Toggle pressed state.

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.

Parameters:

Name Type Attributes Description
pressed boolean optional

An option is being pressed, omit to toggle
Inherited from:
Source:
Toggle pressed state.

toggleScreenReaderMode([screenReaderMode]) #

Toggle visibility of the menu for screen readers.

Parameters:

Name Type Attributes Default Description
screenReaderMode boolean optional
 false
Source:
Toggle visibility of the menu for screen readers.

unbindDocumentKeyDownListener()protected #

Unbind document key down listener.

Overrides:
Source:
Unbind document key down listener.

unbindDocumentKeyPressListener()protected #

Unbind document key down listener.

If you override this, be sure to call this.clearKeyPressBuffer() from your implementation.

Overrides:
Source:
Unbind document key down listener.

unselectItem([unselectedItem]) → {OO.ui.Widget}chainable #

Programmatically unselect an option by its reference. If the widget allows for multiple selections, there may be other items still selected; otherwise, no items will be selected. If no item is given, all selected items will be unselected.

Parameters:

Name Type Attributes Description
unselectedItem OO.ui.OptionWidget optional

Item to unselect, or nothing to unselect all
Inherited from:
Source:

Fires:

Returns:

The widget, for chaining

Type
OO.ui.Widget
Programmatically unselect an option by its reference.

updateDisabled() → {OO.ui.Widget}chainable #

Update the disabled state, in case of changes in parent widget.

Inherited from:
Source:

Returns:

The widget, for chaining

Type
OO.ui.Widget
Update the disabled state, in case of changes in parent widget.

updateItemVisibility()protected #

Update menu item visibility and clipping after input changes (if filterFromInput is enabled) or after items were added/removed (always).

Source:

Update menu item visibility and clipping after input changes (if filterFromInput is enabled) or after items were added/removed (always).

updateThemeClasses() #

Update the theme-provided classes.

This is called in element mixins and widget classes any time state changes. Updating is debounced, minimizing overhead of changing multiple attributes and guaranteeing that theme updates do not occur within an element's constructor

Inherited from:
Source:
Update the theme-provided classes.

Events

add(items, index) #

An add event is emitted when options are added to the select with the #addItems method.

Parameters:

Name Type Description
items Array.<OO.ui.OptionWidget>

Added items
index number

Index of insertion point
Inherited from:
Source:
An add event is emitted when options are added to the select with the #addItems method.

choose(item, selected) #

A choose event is emitted when an item is chosen with the #chooseItem method.

Parameters:

Name Type Description
item OO.ui.OptionWidget

Chosen item
selected boolean

Item is selected
Inherited from:
Source:
A choose event is emitted when an item is chosen with the #chooseItem method.

disable(disabled) #

A 'disable' event is emitted when the disabled state of the widget changes (i.e. on disable and enable).

Parameters:

Name Type Description
disabled boolean

Widget is disabled
Inherited from:
Source:

A 'disable' event is emitted when the disabled state of the widget changes (i.e.

highlight(item) #

A highlight event is emitted when the highlight is changed with the #highlightItem method.

Parameters:

Name Type Description
item OO.ui.OptionWidget | null

Highlighted item
Inherited from:
Source:
A highlight event is emitted when the highlight is changed with the #highlightItem method.

press(item) #

A press event is emitted when the #pressItem method is used to programmatically modify the pressed state of an option.

Parameters:

Name Type Description
item OO.ui.OptionWidget | null

Pressed item
Inherited from:
Source:

A press event is emitted when the #pressItem method is used to programmatically modify the pressed state of an option.

ready() #

The menu is ready: it is visible and has been positioned and clipped.

Source:
The menu is ready: it is visible and has been positioned and clipped.

remove(items) #

A remove event is emitted when options are removed from the select with the #clearItems or #removeItems methods.

Parameters:

Name Type Description
items Array.<OO.ui.OptionWidget>

Removed items
Inherited from:
Source:

A remove event is emitted when options are removed from the select with the #clearItems or #removeItems methods.

select(items) #

A select event is emitted when the selection is modified programmatically with the #selectItem method.

Parameters:

Name Type Description
items Array.<OO.ui.OptionWidget> | OO.ui.OptionWidget | null

Currently selected items
Inherited from:
Source:

A select event is emitted when the selection is modified programmatically with the #selectItem method.

toggle(visible) #

A 'toggle' event is emitted when the visibility of the widget changes.

Parameters:

Name Type Description
visible boolean

Widget is visible
Inherited from:
Source:
A 'toggle' event is emitted when the visibility of the widget changes.