UI-select Component

UI-select component

The UI-select component is used to provide checkbox interface for a specific listing or a specific data set. The component allows selecting a collection of items.

The UI-select component has extended from the Abstract component.

Example integration:


<listing xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Ui:etc/ui_configuration.xsd">
            <filterSelect name="uiSelect">
                <argument name="optionsProvider" xsi:type="configurableObject">
                    <argument name="class" xsi:type="string">Magento\Cms\Model\Page\Source\PageLayout</argument>
                <argument name="data" xsi:type="array">
                    <item name="config" xsi:type="array">
                        <item name="component" xsi:type="string">Magento_Ui/js/form/element/ui-select</item>
                        <item name="template" xsi:type="string">ui/grid/filters/elements/ui-select</item>
                        <item name="dataScope" xsi:type="string">uiSelect</item>
                        <item name="label" xsi:type="string" translate="true">uiSelect</item>


The following configuration can be passed in arguments:

  • Link to any of the following templates
  • Link to the constructor
  • Label to ui-select
  • Default caption
  • Caption if selected more then one elements

The UI-select component supports keyboard navigation.

Navigation keys:

  • Enter key: if focus on the caption - a list of options opens, if focus on the some option - selected or unselected current option
  • Space key: copy ‘Enter key’ functionality
  • Escape key: closes the list of options
  • PageUp key: sets focus to previous option
  • PageDown key: sets focus to next option

UI-select JS component structure

  • Component elements

    The Ui-select component is implemented in the class app\code\Magento\Ui\view\base\web\js\form\element\ui-select.js

    Templates used by this component are:


  • Dependencies on Other Components


  • imports option

    The option defines from where the component receives its data.

    Code samples available in the default configuration:

    imports: {
        options: '${ $.optionsConfig.name }:options'
  • actions option

    You can modify the default actions by renaming their storefront labels

    Code samples available in the default configuration:

    actions: [{
                    value: 'selectAll',
                    label: $t('Select all')
                }, {
                    value: 'deselectAll',
                    label: $t('Deselect all')
                }, {
                    value: 'selectPage',
                    label: $t('Select all on this page')
                }, {
                    value: 'deselectPage',
                    label: $t('Deselect all on this page')

Component options

Title Description Required For Correct Work Type Default Value
options.< option name >.label Options label - String undefined
options.< option name >.value Options value - String undefined
options.< option name >.optgroup Nested level of options - Object undefined
mode Mode overrides default values for some options. In 'simple' mode showCheckbox = chipsEnabled = closeBtn = false. In 'optgroup' mode showCheckbox = openLevelsAction = false, and lastSelectable = optgroupLabels = labelsDecoration = true. - Boolean false
showCheckbox Show checkbox just before option label, select options by checking - Boolean true
chipsEnabled Selected options are shown in ui select's header as deletable chips - Boolean true
closeBtn Show button that closes dropdown - Boolean true
closeBtnLabel Label of the close button - string $t('Done')
levelsVisibility If true, all levels are visible. If is a number, this number of levels are visible. - Boolean/number true
openLevelsAction - Boolean true
showOpenLevelsActionIcon - Boolean true
showTree - Boolean false
separator - String optgroup


Here is an example of configuration of select component. It is used as column filter and has 3 levels of options, with not selectable label for every level, without checkboxes:

view the configuration