Combobox

A Combobox combines a text input with an icon-only chevron button. When activated, a dropdown menu of selectable options displays.

Guidelines

When to use comboboxes

Through comboboxes, users can input text, numbers, symbols or mixed-format strings (unless specifically restricted) while being offered autocomplete options in a dropdown menu.

Use the Combobox component when it's difficult to predict the user's response to a prompt. It provides predefined input values as options, for example common responses, to ease filling out the input with relevant values.

Specifications

1. Icon (optional)
   Icons may be added to simplify the identification of specific combobox inputs.
2. Placeholder text (optional)
   The placeholder text provides an example of what type of information is being requested in the input. The placeholder text should further illustrate and support the combobox input label. However, it should never be the only input description.
3. Chevron button
   An icon-only chevron button opens the menu.
4. Menu
   When the combobox is active, a menu with options is displayed.

Component limitations

The base min-width for the Combobox 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.

If the text in the Combobox component exceeds the available space, it will overflow horizontally.

By default, when the menu is expanded, all menu items are displayed. However, if the menu height is limited, the remaining menu items will be accessible via scrolling.

Refer to the Combobox component in Codex Figma.

Interaction states

Comboboxes have the following visually separate states:

1. Default
2. Hover on input
3. Hover on button
4. Disabled
5. Active and hover on one of the menu items
6. Typing in the input and having a menu item selected based on the matching text
7. Combobox filled with one selected menu option
8. Active with no results

Best practices

Consider the following recommendations when using comboboxes.

Icon

Do:

• Use a start icon that complements the placeholder text.

Don't:

• Use icons that are difficult to understand or do not clearly convey their purpose.

Keyboard navigation

Key	Function
Tab	It places the focus within the input of the Combobox and opens its menu. It also moves the focus to the next interactive element in tab order.
Shift + Tab	When the focus is placed within the Combobox input, it moves the focus to the previous interactive element.
Down arrow	When the Combobox is focused, 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 Combobox is focused, it opens the menu. When the menu is open, it navigates through menu options.
Enter	It opens the menu when the focus is placed on the Combobox. If the menu is open, it closes the menu. If the focus is placed in any of the options within the menu, the focused option is selected.
Esc	When the menu it’s open, it closes the menu.
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.

Demos

Basic Usage

The Combobox component combines a menu of selectable items with a text box that can accept arbitrary input from the user. The component should receive a v-model:selected binding from its parent as well as an array of menu items (which can be empty).

Selected value:

• a
• b
• c

NPM

<template>
	<div>
		<p class="cdx-docs-demo-text">
			Selected value: {{ selection }}
		</p>

		<cdx-combobox
			v-model:selected="selection"
			:menu-items="menuItems"
			placeholder="Type or choose an option"
		/>
	</div>
</template>

<script>
import { defineComponent } from 'vue';
import { CdxCombobox } from '@wikimedia/codex';

const menuItems = [
	{ label: 'a', value: 'a' },
	{ label: 'b', value: 'b' },
	{ label: 'c', value: 'c' }
];

export default defineComponent( {
	name: 'ComboBoxBasic',
	components: { CdxCombobox },

	data() {
		return {
			menuItems,
			selection: ''
		};
	}
} );
</script>

MediaWiki

<template>
	<div>
		<p class="cdx-docs-demo-text">
			Selected value: {{ selection }}
		</p>

		<cdx-combobox
			v-model:selected="selection"
			:menu-items="menuItems"
			placeholder="Type or choose an option"
		></cdx-combobox>
	</div>
</template>

<script>
const { defineComponent } = require( 'vue' );
const { CdxCombobox } = require( '@wikimedia/codex' );

const menuItems = [
	{ label: 'a', value: 'a' },
	{ label: 'b', value: 'b' },
	{ label: 'c', value: 'c' }
];

module.exports = defineComponent( {
	name: 'ComboBoxBasic',
	components: { CdxCombobox },

	data() {
		return {
			menuItems,
			selection: ''
		};
	}
} );
</script>

Name	Value
View
Reading direction	Left to right (LTR) Right to left (RTL)

Clearable, with start icon

Valid TextInput props like startIcon, endIcon, and clearable will be passed on to the embedded TextInput.

Selected value:

• a
• b
• c

NPM

<template>
	<div>
		<p class="cdx-docs-demo-text">
			Selected value: {{ selection }}
		</p>

		<cdx-combobox
			v-model:selected="selection"
			:menu-items="menuItems"
			placeholder="Type or choose an option"
			:start-icon="icon"
			:clearable="true"
		/>
	</div>
</template>

<script>
import { defineComponent } from 'vue';
import { CdxCombobox } from '@wikimedia/codex';
import { cdxIconSearch } from '@wikimedia/codex-icons';

const menuItems = [
	{ label: 'a', value: 'a' },
	{ label: 'b', value: 'b' },
	{ label: 'c', value: 'c' }
];

export default defineComponent( {
	name: 'ComboBoxClearableStartIcon',
	components: { CdxCombobox },

	data() {
		return {
			menuItems,
			selection: '',
			icon: cdxIconSearch
		};
	}
} );
</script>

MediaWiki

<template>
	<div>
		<p class="cdx-docs-demo-text">
			Selected value: {{ selection }}
		</p>

		<cdx-combobox
			v-model:selected="selection"
			:menu-items="menuItems"
			placeholder="Type or choose an option"
			:start-icon="icon"
			:clearable="true"
		></cdx-combobox>
	</div>
</template>

<script>
const { defineComponent } = require( 'vue' );
const { CdxCombobox } = require( '@wikimedia/codex' );
const { cdxIconSearch } = require( './icons.json' );

const menuItems = [
	{ label: 'a', value: 'a' },
	{ label: 'b', value: 'b' },
	{ label: 'c', value: 'c' }
];

module.exports = defineComponent( {
	name: 'ComboBoxClearableStartIcon',
	components: { CdxCombobox },

	data() {
		return {
			menuItems,
			selection: '',
			icon: cdxIconSearch
		};
	}
} );
</script>

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 Combobox to bold the label text and hide the text overflow of the descriptions.

• cameraoptical device for recording or transmitting photographic images or videos
• bookwritten text that can be published in printed or electronic form
• clockinstrument that measures the passage of time

NPM

<template>
	<div>
		<cdx-combobox
			v-model:selected="selection"
			:menu-items="menuItems"
			:menu-config="menuConfig"
			placeholder="Type or choose an option"
		/>
	</div>
</template>

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

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

export default defineComponent( {
	name: 'ComboboxComplexMenuItems',
	components: { CdxCombobox },

	data() {
		return {
			menuItems,
			selection: '',
			menuConfig: {
				boldLabel: true,
				hideDescriptionOverflow: true
			}
		};
	}
} );
</script>

MediaWiki

<template>
	<div>
		<cdx-combobox
			v-model:selected="selection"
			:menu-items="menuItems"
			:menu-config="menuConfig"
			placeholder="Type or choose an option"
		></cdx-combobox>
	</div>
</template>

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

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

module.exports = defineComponent( {
	name: 'ComboboxComplexMenuItems',
	components: { CdxCombobox },

	data() {
		return {
			menuItems,
			selection: '',
			menuConfig: {
				boldLabel: true,
				hideDescriptionOverflow: true
			}
		};
	}
} );
</script>

With custom menu item display

Like other menu-style components (Select, Lookup, etc.), a custom template can be provided via the #menu-item slot. In this example, only the menu item's icon is displayed in the menu.

NPM

<template>
	<div>
		<cdx-combobox
			v-model:selected="selection"
			:menu-items="menuItems"
			placeholder="Type or choose an option"
		>
			<template #menu-item="{ menuItem }">
				<cdx-icon v-if="menuItem.icon" :icon="menuItem.icon" />
			</template>
		</cdx-combobox>
	</div>
</template>

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

const menuItems = [
	{ value: 'camera', icon: cdxIconCamera },
	{ value: 'book', icon: cdxIconBook },
	{ value: 'clock', icon: cdxIconClock }
];

export default defineComponent( {
	name: 'ComboboxCustomMenuItem',
	components: { CdxCombobox, CdxIcon },

	data() {
		return {
			menuItems,
			selection: ''
		};
	}
} );
</script>

MediaWiki

<template>
	<div>
		<cdx-combobox
			v-model:selected="selection"
			:menu-items="menuItems"
			placeholder="Type or choose an option"
		>
			<template #menu-item="{ menuItem }">
				<cdx-icon v-if="menuItem.icon" :icon="menuItem.icon"></cdx-icon>
			</template>
		</cdx-combobox>
	</div>
</template>

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

const menuItems = [
	{ value: 'camera', icon: cdxIconCamera },
	{ value: 'book', icon: cdxIconBook },
	{ value: 'clock', icon: cdxIconClock }
];

module.exports = defineComponent( {
	name: 'ComboboxCustomMenuItem',
	components: { CdxCombobox, CdxIcon },

	data() {
		return {
			menuItems,
			selection: ''
		};
	}
} );
</script>

With "no results" content

A non-interactive "no results" message can be displayed via the no-results slot. If populated, this slot will automatically display when there are zero menu items.

• Sorry, no options to display.

NPM

<template>
	<div>
		<cdx-combobox
			v-model:selected="selection"
			:menu-items="menuItems"
			placeholder="Type or choose an option"
		>
			<template #no-results>
				Sorry, no options to display.
			</template>
		</cdx-combobox>
	</div>
</template>

<script>
import { defineComponent } from 'vue';
import { CdxCombobox } from '@wikimedia/codex';

const menuItems = [];

export default defineComponent( {
	name: 'ComboboxNoResults',
	components: { CdxCombobox },

	data() {
		return {
			menuItems,
			selection: ''
		};
	}
} );
</script>

MediaWiki

<template>
	<div>
		<cdx-combobox
			v-model:selected="selection"
			:menu-items="menuItems"
			placeholder="Type or choose an option"
		>
			<template #no-results>
				Sorry, no options to display.
			</template>
		</cdx-combobox>
	</div>
</template>

<script>
const { defineComponent } = require( 'vue' );
const { CdxCombobox } = require( '@wikimedia/codex' );

const menuItems = [];

module.exports = defineComponent( {
	name: 'ComboboxNoResults',
	components: { CdxCombobox },

	data() {
		return {
			menuItems,
			selection: ''
		};
	}
} );
</script>

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.

• One
• Two
• Three
• Four
• Five
• Six
• Seven
• Eight
• Nine
• Ten
• Eleven
• Twelve

NPM

<template>
	<div>
		<cdx-combobox
			v-model:selected="selection"
			:menu-items="menuItems"
			:menu-config="menuConfig"
			placeholder="Type or choose an option"
		/>
	</div>
</template>

<script>
import { defineComponent } from 'vue';
import { CdxCombobox } from '@wikimedia/codex';

const menuItems = [
	{ label: 'One', value: '1' },
	{ label: 'Two', value: '2' },
	{ label: 'Three', value: '3' },
	{ label: 'Four', value: '4' },
	{ label: 'Five', value: '5' },
	{ label: 'Six', value: '6' },
	{ label: 'Seven', value: '7' },
	{ label: 'Eight', value: '8' },
	{ label: 'Nine', value: '9' },
	{ label: 'Ten', value: '10' },
	{ label: 'Eleven', value: '11' },
	{ label: 'Twelve', value: '12' }
];

export default defineComponent( {
	name: 'ComboboxWithScroll',
	components: { CdxCombobox },

	data() {
		return {
			menuConfig: {
				visibleItemLimit: 6
			},
			menuItems,
			selection: ''
		};
	}
} );
</script>

MediaWiki

<template>
	<div>
		<cdx-combobox
			v-model:selected="selection"
			:menu-items="menuItems"
			:menu-config="menuConfig"
			placeholder="Type or choose an option"
		></cdx-combobox>
	</div>
</template>

<script>
const { defineComponent } = require( 'vue' );
const { CdxCombobox } = require( '@wikimedia/codex' );

const menuItems = [
	{ label: 'One', value: '1' },
	{ label: 'Two', value: '2' },
	{ label: 'Three', value: '3' },
	{ label: 'Four', value: '4' },
	{ label: 'Five', value: '5' },
	{ label: 'Six', value: '6' },
	{ label: 'Seven', value: '7' },
	{ label: 'Eight', value: '8' },
	{ label: 'Nine', value: '9' },
	{ label: 'Ten', value: '10' },
	{ label: 'Eleven', value: '11' },
	{ label: 'Twelve', value: '12' }
];

module.exports = defineComponent( {
	name: 'ComboboxWithScroll',
	components: { CdxCombobox },

	data() {
		return {
			menuConfig: {
				visibleItemLimit: 6
			},
			menuItems,
			selection: ''
		};
	}
} );
</script>

Disabled

• a
• b
• c

NPM

<template>
	<div>
		<cdx-combobox
			v-model:selected="selection"
			:menu-items="menuItems"
			:disabled="true"
			placeholder="Type or choose an option"
		/>
	</div>
</template>

<script>
import { defineComponent } from 'vue';
import { CdxCombobox } from '@wikimedia/codex';

const menuItems = [
	{ label: 'a', value: 'a' },
	{ label: 'b', value: 'b' },
	{ label: 'c', value: 'c' }
];

export default defineComponent( {
	name: 'ComboBoxDisabled',
	components: { CdxCombobox },

	data() {
		return {
			menuItems,
			selection: ''
		};
	}
} );
</script>

MediaWiki

<template>
	<div>
		<cdx-combobox
			v-model:selected="selection"
			:menu-items="menuItems"
			:disabled="true"
			placeholder="Type or choose an option"
		></cdx-combobox>
	</div>
</template>

<script>
const { defineComponent } = require( 'vue' );
const { CdxCombobox } = require( '@wikimedia/codex' );

const menuItems = [
	{ label: 'a', value: 'a' },
	{ label: 'b', value: 'b' },
	{ label: 'c', value: 'c' }
];

module.exports = defineComponent( {
	name: 'ComboBoxDisabled',
	components: { CdxCombobox },

	data() {
		return {
			menuItems,
			selection: ''
		};
	}
} );
</script>

Form field

A Combobox 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.

Input type What kind of data does the function accept?

• boolean
• function
• object
• string

Choose a type from the menu or enter a custom type.

NPM

<template>
	<cdx-field>
		<cdx-combobox
			v-model:selected="selection"
			:menu-items="menuItems"
		/>
		<template #label>
			Input type
		</template>
		<template #description>
			What kind of data does the function accept?
		</template>
		<template #help-text>
			Choose a type from the menu or enter a custom type.
		</template>
	</cdx-field>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxCombobox, CdxField } from '@wikimedia/codex';

export default defineComponent( {
	name: 'ComboboxField',
	components: { CdxCombobox, CdxField },
	setup() {
		const selection = ref( '' );
		const menuItems = [
			{ value: 'boolean' },
			{ value: 'function' },
			{ value: 'object' },
			{ value: 'string' }
		];

		return {
			selection,
			menuItems
		};
	}
} );
</script>

MediaWiki

<template>
	<cdx-field>
		<cdx-combobox
			v-model:selected="selection"
			:menu-items="menuItems"
		></cdx-combobox>
		<template #label>
			Input type
		</template>
		<template #description>
			What kind of data does the function accept?
		</template>
		<template #help-text>
			Choose a type from the menu or enter a custom type.
		</template>
	</cdx-field>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxCombobox, CdxField } = require( '@wikimedia/codex' );

module.exports = defineComponent( {
	name: 'ComboboxField',
	components: { CdxCombobox, CdxField },
	setup() {
		const selection = ref( '' );
		const menuItems = [
			{ value: 'boolean' },
			{ value: 'function' },
			{ value: 'object' },
			{ value: 'string' }
		];

		return {
			selection,
			menuItems
		};
	}
} );
</script>

Vue usage

TextInput props apply

This component contains a TextInput component. You can bind TextInput props to this component and they will be passed to the TextInput within.

Attributes passed to input

This component will pass any HTML attributes applied to it, except for CSS class, to the <input> element within the component.

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.	string|number
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; }
status	status property of the TextInput component	ValidationStatusType	'default'

Events

Event name	Properties	Description
input	event InputEvent	When the input value changes via direct use of the input
change	event Event	When an input value change is committed by the user (e.g. on blur)
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	selected string|number - The new selected value	When the selected value changes.
focus	event FocusEvent	When the input comes into focus
blur	event FocusEvent	When the input loses focus

Slots

Name	Description	Bindings
menu-item	Display of an individual item in the menu	menu-item MenuItemData - The current menu item
no-results	Message to show if there are no menu items to display.