Skip to content
On this page

Select

An input with a dropdown menu of predefined selectable items.

Menu items are provided as an array of MenuItemData types, and v-model is used to bind the current selection's value.

Demos

Configurable

NameValue
Props
disabled
defaultLabel
defaultIcon
status
View
Reading direction
Note: For icon properties, the relevant icon also needs to be imported from the @wikimedia/codex-icons package. See the usage documentation for more information.

Basic Usage

Menu items must have a value, and can have a label to display in the UI. If no label is provided (like the third menu item in this example), the value will be displayed.

With menu item icons and descriptions

Items are displayed via the MenuItem component—see the MenuItem docs for more options. In this example, a menuConfig object is passed to the Select to bold the label text and hide the text overflow of the descriptions.

With custom menu item display

The menu-item scoped slot enables you to customize the display of each menu item, with a binding for the menuItem. In this example, only the menu item's icon is displayed in the menu.

With custom label display

The label scoped slot enables you to customize the display of the label, with bindings for the selectedMenuItem and the defaultLabel.

With configurable scroll

By default, all menu items are displayed when the menu is expanded. To limit the height of the menu and enable scrolling, use the visibleItemLimit property of the menuConfig prop.

Form field

A Select can be wrapped in the Field component to add features like a semantic label, description and help text, validation messages, and more. See the Field page for more information.

Select a search interface to use by default
Special:Search is better for searching text-based items like articles. Special:MediaSearch provides a better interface for searching files.

Usage

Props

Prop nameDescriptionTypeValuesDefault
menuItems(required)Menu items. See the MenuItemData type.MenuItemData[]-
selected(required)Value of the current selection.

Must be bound with v-model:selected.

The property should be initialized to null rather than using a falsy value.
string|number|null-
defaultLabelLabel to display when no selection has been made.string-''
disabledWhether the dropdown is disabled.boolean-false
menuConfigConfiguration for various menu features. All properties default to false.

See the MenuConfig type.
MenuConfig-() => { return {} as MenuConfig; }
defaultIconAn icon at the start of the select element displayed when no selection has been made.Icon|undefined-undefined
statusstatus attribute of the input.ValidationStatusType'default', 'error''default'

Events

Event namePropertiesDescription
load-moreWhen the user scrolls towards the bottom of the menu.

If it is possible to add or load more menu items, then now would be a good moment so that the user can experience infinite scrolling.
update:selectedmodelValue string|number|null - The new model valueWhen the selection value changes.

Slots

NameDescriptionBindings
labelDisplay of the current selection or default labelselected-menu-item MenuItemData, undefined - The currently selected menu
item
default-label string - The default label, provided via a prop
menu-itemDisplay of an individual item in the menumenu-item MenuItemData - The current menu item

CSS-only version

Markup structure

The CSS-only version of this component uses the native <select> element. This element will be styled to match the Vue version, but the menu will use native browser styles.

Disabled

Add the disabled attribute to the <select> element to get a disabled element with appropriate styles.