Select

A Select is an input with a dropdown menu of predefined, selectable items.

Guidelines

Using selects

Selects must feature a label stating the current selection and a menu of at least two, but preferably three or more, options.

Use the Select component when users need to choose an option from a predefined list. For example, to select a country or category. If the list of options is too long, consider using Combobox instead. If users need a multi-selection, use a Checkbox group instead.

Specifications

Specification of Select.

Icon (optional)
An icon can simplify the identification of the available options in selects.
Label
Dropdown labels communicate what selections the component conveys. Labels are required for selects.
Arrow indicator
Selects have a button-like appearance, and include a mandatory arrow indicator to communicate that they can be expanded.
Menu
When the select is open, a menu with options is displayed.

The base min-width for the Select component is set at @size-1600 (equivalent to 256px in the default Codex theme), but it can be customized to a smaller width if needed. There is no maximum width limit.

The Select menu must contain a minimum of 2 items. While the number of visible options can vary, we recommend around 5 for optimal usability. If there are more options than what's initially visible, a scrollbar will appear for users to access them.

Refer to the Select component in Codex Figma.

Interaction states

Selects have the following visually separate states:

States of the Select component: default, hover, focus, error, disabled, active, and filled with one option selected from the dropdown menu.

Default
Hover
Focus
Error
Disabled
Active select with menu displayed
Active select and hover on one of the menu options
Active select and one of the menu options being pressed
Active select with one of the menu options selected
Filled (with one option from the menu selected)

Accessibility note

The disabled state does not meet our minimum color contrast rules. WCAG 2.1 states that “…part[s] of an inactive user interface component […] have no contrast requirement”. ^[1]
Provide sufficient information in a disabled element's context, so the user can understand what is disabled and how to enable it (if applicable).

Best practices

Consider the following recommendations when using selects.

Icon

Do:

Include the start icon in the Select if the selected menu item contains an icon, which is then displayed in the Select.

Don't:

Include a start icon in the Select component by default unless a menu item with an icon has been selected.

Content

Select text introduces the options available in a drop-down menu.

Selects conveying examples of clear placeholder text.

Do:

Indicate clearly the kinds of options that follow. Clear & Trustworthy

Selects conveying examples of vague placeholder text.

Don't:

Make the select label vague or generic. Clear & Trustworthy
Write a part of a sentence that is completed by the choices. Translatable

Key	Function
`Down arrow`	When the focus is placed on the input, it opens the menu. When the menu is open, it navigates through menu options. If pressed at the last visible option, it scrolls to the next "hidden" menu item.
`Up arrow`	When the focus is placed on the input, it opens the menu. When the menu is open, it navigates through menu options.
`Enter`	It expands and collapses the menu when the focus is placed on the Select. If the focus is placed in any of the options within the menu, the focused option is selected.
`Esc`	This key closes the menu when it is open.
`Home`	Optionally, it moves the focus to the first option. Optionally, in a single-select listbox, selection may also move with focus. Supporting this key is strongly recommended for lists with more than five options.
`End`	Optionally, it moves the focus to the last option. Optionally, in a single-select listbox, selection may also move with focus. Supporting this key is strongly recommended for lists with more than five options.

References

Web Content Accessibility Guidelines (WCAG) 2.1 – Success Criterion 1.4.3 Contrast (Minimum)

Demos

Configurable

Name	Value
Props
disabled
defaultLabel
defaultIcon
status	default error
View
Reading direction	Left to right (LTR) Right to left (RTL)
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.

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.

NPMMediaWiki

vue

<template>
	<cdx-select
		v-model:selected="selection"
		:menu-items="menuItems"
		:menu-config="menuConfig"
		default-label="Choose an option"
	/>
</template>

<script>
import { defineComponent } from 'vue';
import { CdxSelect } from '@wikimedia/codex';
import { cdxIconCamera, cdxIconBook, cdxIconClock } from '@wikimedia/codex-icons';

const menuItems = [
	{
		value: 'camera',
		label: 'Camera',
		description: 'optical device for recording or transmitting photographic images or videos',
		icon: cdxIconCamera
	},
	{
		value: 'book',
		label: 'Book',
		description: 'written text that can be published in printed or electronic form',
		icon: cdxIconBook
	},
	{
		value: 'clock',
		label: 'Clock',
		description: 'instrument that measures the passage of time',
		icon: cdxIconClock
	}
];

export default defineComponent( {
	name: 'SelectComplexMenuItems',
	components: { CdxSelect },
	data() {
		return {
			menuItems,
			selection: null,
			menuConfig: {
				boldLabel: true,
				hideDescriptionOverflow: true
			}
		};
	}
} );
</script>

vue

<template>
	<cdx-select
		v-model:selected="selection"
		:menu-items="menuItems"
		:menu-config="menuConfig"
		default-label="Choose an option"
	></cdx-select>
</template>

<script>
const { defineComponent } = require( 'vue' );
const { CdxSelect } = require( '@wikimedia/codex' );
const { cdxIconCamera, cdxIconBook, cdxIconClock } = require( './icons.json' );

const menuItems = [
	{
		value: 'camera',
		label: 'Camera',
		description: 'optical device for recording or transmitting photographic images or videos',
		icon: cdxIconCamera
	},
	{
		value: 'book',
		label: 'Book',
		description: 'written text that can be published in printed or electronic form',
		icon: cdxIconBook
	},
	{
		value: 'clock',
		label: 'Clock',
		description: 'instrument that measures the passage of time',
		icon: cdxIconClock
	}
];

// @vue/component
module.exports = defineComponent( {
	name: 'SelectComplexMenuItems',
	components: { CdxSelect },
	data() {
		return {
			menuItems,
			selection: null,
			menuConfig: {
				boldLabel: true,
				hideDescriptionOverflow: true
			}
		};
	}
} );
</script>

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.

Search interface 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.

Vue usage

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

Props

Prop name	Description	Type	Default
`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`
`defaultLabel`	Label to display when no selection has been made.	`string`	`''`
`disabled`	Whether the dropdown is disabled.	`boolean`	`false`
`menuConfig`	Configuration for various menu features. All properties default to false. See the MenuConfig type.	`MenuConfig`	`() => { return {} as MenuConfig; }`
`defaultIcon`	An icon at the start of the select element displayed when no selection has been made.	`Icon\|undefined`	`undefined`
`status`	`status` attribute of the input.	`ValidationStatusType`	`'default'`

Events

Event name	Properties	Description
`load-more`		When 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:selected`	modelValue `string\|number\|null` - The new model value	When the selection value changes.

Slots

Name	Description	Bindings
label	Display of the current selection or default label	selected-menu-item `MenuItemData, undefined` - The currently selected menu default-label `string` - The default label, provided via a prop
menu-item	Display of an individual item in the menu	menu-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.

Select

Guidelines

Using selects

Specifications

Interaction states

Best practices

Icon

Content

Keyboard navigation

References

Demos

Configurable

Basic Usage

With menu item icons and descriptions

With custom menu item display

With custom label display

With configurable scroll

Form field

Vue usage

Props

Events

Slots

CSS-only version

Markup structure

Disabled

Select ​

Guidelines ​

Using selects ​

Specifications ​

Interaction states ​

Best practices ​

Icon ​

Content ​

Keyboard navigation ​

References ​

Demos ​

Configurable ​

Basic Usage ​

With menu item icons and descriptions ​

With custom menu item display ​

With custom label display ​

With configurable scroll ​

Form field ​

Vue usage ​

Props ​

Events ​

Slots ​

CSS-only version ​

Markup structure ​

Disabled ​

Select

Guidelines

Using selects

Specifications

Interaction states

Best practices

Icon

Content

Keyboard navigation

References

Demos

Configurable

Basic Usage

With menu item icons and descriptions

With custom menu item display

With custom label display

With configurable scroll

Form field

Vue usage

Props

Events

Slots

CSS-only version

Markup structure

Disabled