Select

Single Select Multi Select Smart Search

Single Select

It gives users the ability to choose a single item from a list of dropdown menu items. It's usually found in forms or inline edit.

Anatomy

1. Label: Labels should be sentence case as short as possible while clearly explaining the content of the menu.
2. Menu: Contains the list of all selectable items. These can be grouped into sub-categories under headings. Each item can also contain an icon or color.

Best Practices

1. Order your list of options in a way that will make the most sense to the user.
2. Remove options that rarely get used.
3. Don't overwhelm the user with too many options.

Content Guidelines

1. Use concise and descriptive labels so that users clearly know the purpose of the selection. For example, use a "Save to..." label for a list containing options such as "Cloud, Local drive, CD".
2. Keep options to a single line of text.
3. Use commonly known terms for your options, make sure they're clear and direct.

Styles

// Include all components' styles.
@import "shared-ui";

// Include styles for component only.
@import "~@wpmudev/shared-ui/scss/select";

Note: When importing component styles only you will also need to import functions, colors, variables, and other basic files that work together with select file. For enabling monochrome add class .sui-elements-accessible in body wrapper.

JavaScript Instantiation

This is the basic configuration for each variation of the select component.

Default

$( '#unique-id' ).SUIselect2();

Dropdown option with icon

$( '#unique-id' ).SUIselect2({
	templateResult: SUI.select.formatIcon,
	templateSelection: SUI.select.formatIconSelection,
	escapeMarkup: function( markup ) {
		return markup;
	}
});

Dropdown option with color

$( '#unique-id' ).SUIselect2({
	templateResult: SUI.select.formatColor,
	templateSelection: SUI.select.formatColorSelection,
	escapeMarkup: function( markup ) {
		return markup;
	}
});

Smart Search

$( '#unique-id' ).SUIselect2({
	minimumInputLength: 2,
	maximumSelectionLength: 1
});

By adding sui-select class there's no need for any JavaScript instantiation but if you need to pass data through JS or any other configuration, you can do it by using .SUIselect2( 'destroy' ) before calling .SUIselect2().

To configure custom options when you initialize SUIselect2, simply pass an object in your call to .SUIselect2().

JS options

This is a list with the most common SUIselect2 configuration options.

Since SUIselect2 is based on Select2, you can find more configuration options listed here.

data-* attributes

It is recommended that you declare your configuration options by passing in an object when initializing SUIselect2. However, you may also define your configuration options by using the HTML5 data-* attributes, which will override any options set when initializing SUIselect2 and any defaults.

Classes

Single select element by default occupies a single row and the full width of it, but there are times when you need to use it as an inline element. For that, you need to add sui-select-inline class to select element.