vue-extended-multiselect is a component that simplifies the customization of the built-in select element. It allows developers to avoid writing excessive CSS rules by using built-in themes and prevents common issues when handling different types of options.
The options list can be decorated with extra slots, making it more informative and user-friendly. A thorough filtering process for the raw options provided by the developer helps prevent sudden errors from unintended option formats. Switchable warnings assist in catching potential errors during development.
The component includes tools for managing selected options, letting users control how many are displayed and deselect them quickly. Developers can also customize these tools. Furthermore, various slots are available to customize the options list, selected elements in multiple-select mode, and other interactive elements to your liking.
You can use this component in your web applications based on the Vue 2 framework. If you are using newer versions of Vue, please use the vue3-extended-multiselect package instead. These two packages are identical in functionality.
https://vue3-extended-multiselect.surge.sh/
These examples are based on Vue3, but you can use the same props/slots/events in Vue2 version.
npm install --save vue-extended-multiselect
yarn add vue-extended-multiselect
import VueExtendedMultiselect from "vue-extended-multiselect";import type { UnionOptionType } from "vue-extended-multiselect";| Prop name | Prop type | Prop appointment | Prop default value | Prop values |
|---|---|---|---|---|
| autoSelect CreatedOption |
Boolean | Determines whether to select just now created option automatically. | false | — |
| autoSelect SearchValue |
Boolean | Determines whether to take search value from current selected option if "multiple" prop equals false. | false | — |
| clearBySelect WhenMultiple |
Boolean | Determines whether to clear search field by option selection. | false | — |
| createOnThe Go |
Boolean | Allows user to create new options from search field. | false | — |
| default Expanded |
Boolean | Determines whether options list should be expanded by default. | false | — |
| disabled | Boolean | Disables extended multiselect. | false | — |
| dropdownDisabled | Boolean | Disables dropdown toggle. | false | — |
| highlight Options |
Boolean | Switches options highlighting while hovering. | true | — |
| loading | Boolean | Switches loading state of extended multiselect. | false | — |
| multiple | Boolean | Allows user to select multiple options. | false | — |
| noResults BlockShown |
Boolean | Determines whether to show special hint if no options were found. | true | — |
| resetSearch ByValue |
Boolean | Determines whether to clear search field by selection/deselection of options. | true | — |
| searchFilter Active |
Boolean | Allows user to use internal search for options. | true | — |
| simpleEvents | Boolean | Switches full payload of extended multiselect events. | true | — |
| selected Options Shown |
Boolean | Determines whether to show selected options in options list. | false | — |
| showClearIcon | Boolean | Allows user to deselect all options by special icon. | false | — |
| showDeselect IconLoader |
Boolean | Determines whether to show loader icon in multiple options block if "loading" prop equals true | true | — |
| showInsert Warnings |
Boolean | Determines whether to show useful internal warnings in console. | false | — |
| showMarker | Boolean | Determines whether to show slot with special marker beside option in options list. | false | — |
| showSearch Field |
Boolean | Determines whether to show search field which allows user to search for options with internal search. | true | — |
| toggleMultiple BlocksLimit |
Boolean | Allows user to increase limit of shown elements with selected options by special icon. | false | — |
| toggleOptions BySelect |
Boolean | Determines whether to roll up options list by selection of option. | true | — |
| togglingSaves SearchValue |
Boolean | Determines whether to save current search value if display of options list was toggled. | true | — |
| wrongCurrent Value |
Boolean | Determines whether to define special class for extended multiselect if value is wrong or if irregularity of value is defined by user. | false | — |
| createOption Placeholder |
String | Placeholder for the search field to be used if user is allowed to create new options. | "Select or create features" | — |
| createOption Type |
String | Defines kind for all options which will be created by user. | "primitive" | "primitive", "array", "object" |
| disableByField | String | Determines a field in options of type "object" which value will be used to disable such options. | "disabled" | — |
| emptyObjects Placeholder |
String | Placeholder for options of type "object" or Array instances which length/keys length equals 0. | "Empty Object/ Array" |
— |
| errorBorder Color |
String | Defines "border-color" css-property for extended multiselect with wrong value. | "#FF0000" | — |
| iconFilter | String | Defines svg-filter with color settings for all icons except loader. | "basic" | "basic", "black", "green" |
| iconSize | String | Defines sizes for all icons in pixels except loader. | "large" | "large", "medium", "small" |
| label | String | Defines field in options of type "object" that will be the label of option. | "label" | — |
| loaderIcon Filter |
String | Defines svg-filter with color settings for loader icon. | "loader-default" | "loader-default", "basic", "slate-grey", "slate-blue", "teal", "strict" |
| placeholder | String | Placeholder for search field to be used if user is not allowed to create new options. | "Select features" | — |
| searchByField | String | Determines field in options of type "object" to use in internal search. | "" | — |
| themeType | String | Defines overall color theme for extended multiselect. | "basic" | "basic", "slate-grey", "slate-blue", "teal", "strict" |
| toggle Appearance Side |
String | Defines which side options list will be displayed on. | "auto" | "auto", "atop", "under" |
| toggleIcon | String | Defines kind of toggle icon from icons collection. | "base-arrow" | "base-arrow", "double-arrow", "wide-arrow", "circle-arrow", "inner-arrow", "triangle-arrow", "triangle-circle-arrow" |
| anyOption Wrapper BlockHeight |
Number | Defines "height" css-property for each option in options list. | 30 | — |
| increase Display By |
Number | Defines gap which increases limit of displayed elements with selected options. | 5 | — |
| maxOptions Count |
Number | Maximal limit of selected options. | null | — |
| minOptions Count |
Number | Minimal limit of selected options. | null | — |
| multipleBlocks Limit |
Number | Defines limit of displayed elements with selected options. | null | — |
| optionsCount Restriction |
Number | Defines maximal limit of options list length. | null | — |
| toggleMax Height |
Number | Defines maximal value in pixels of "max-height" css-property for options list. | 400 | — |
| toggleMin Height |
Number | Defines minimal value in pixels of "max-height" css-property for options list. | null | — |
| createOption Fields |
Array | Defines a list of fields for options of type "object" created by user. | ["label"] | — |
| disabled Primitive Options |
Array | Defines a list of primitive options which will be disabled for selection. | [] | — |
| options | Array | Raw options list. | [] | — |
| optionsPadding | Array | Defines a list with "padding-top", "padding-left", "padding-bottom" and "padding-right" css-properties for options in options list. Property "padding-top" matches index zero. Property "padding-right" matches index three. | [] | — |
| preselected Options |
Array | Defines a list of options that will be select by default. | [] | — |
| specialKeys Block |
Array | Defines a list of keys which in combination with mouse buttons or "enter" key will prevent selection of option. | [] | "alt", "ctrl", "shift" |
| createCustom OptionLabel |
Function | Defines function that creates custom label for each option. | (option) => null | — |
| multipleBlocks LimitMessage |
Function | Defines function that creates notification when maximal limit of selected options has been reached. | (number) => `and ${number} more items` | — |
| inputId | String, Number | "id" attribute of search field. | null | — |
| preselected Option |
UnionPropType (from types) | Defines options that will be select by default. | null | — |
| value | Array | Defines value of extended multiselect that can be used in "v-model". | [] | — |
| Slot name | Slot appointment | Slot scope |
|---|---|---|
| cancel | Button that deselects all options. | cancel — function that deselects all options |
| labelBlock | Element with single selected option that is shown if search field display is disabled. | labelBlockValue — option label |
| lessThanLimit | Message displayed if minimal limit of selected options has not been reached. | — |
| listHeader | Element at the top of options list for information content. | — |
| listFooter | Element at the bottom of options list for information content. | — |
| marker | Marker that indicates state of option selection. | selected — flag to determine markers for selected options |
| maxElements | Message displayed if maximal limit of elements with selected options has been shown. | — |
| moreThanLimit | Message displayed if maximal limit of selected options has been reached. | — |
| multipleBlocks | Block with selected options and other multiple select slots | selectedOptions — list of selected options,deselectBlock — function that deselects option and removes element that contained it |
| noResults | Message displayed if no options have been found by internal search. | — |
| noOptions | Message displayed if given options list is empty. | — |
| option | Option in options list with its label. | option — option from options list,createCustomOptionLabel — function that creates custom label for each option |
| optionBlock | Element with selected option and its label. | label — option label,deselectBlock — function that deselects option and removes element that contained it,index — option index |
| showMore | Button that increases limit of displayed elements with selected options. | showMoreOptions — function that increases limit of displayed elements with selected options |
| toggle | Button that toggles options list display. | toggleOptionsList — function that toggles options list display |
| Event name | Event appointment | Listener method | Simplified event payload | Fields of object with full event payload |
|---|---|---|---|---|
| pattern-changed | Change value of search field. | @pattern-changed | value — pattern of inner search for available options |
value — pattern of inner search for available options,inputId — id of search field set by "id" prop |
| select | Selection of option. | @select | option — just now selected option |
option — just now selected option,inputId — id of search field set by "id" prop |
| clean | Removal of all options or singe option. | @clean | option/options — just now deselected option or array with just now deselected options |
option/options — just now deselected option or array with just now deselected options,inputId — id of search field set by "id" prop |
| option-created | Creation of new option by user. | @option-created | option — option created by user |
option/options — option created by user,inputId — id of search field set by "id" prop |
| active | Dropdown options list expanding. | @active | — | inputId — id of search field set by "id" prop |
| close | Rolling up dropdown options list. | @close | options — array of selected options |
options — array of selected options,inputId — id of search field set by "id" prop |
| increase | Increasing current limit of displayed elements with selected options. | @increase | limit — current limit of options to be shown next |
limit — current limit of options to be shown next,inputId — id of search field set by "id" prop |
Vue extended multiselect provides following css-variables:
--basic-color: #708090;
--basic-transparent: rgba(112, 128, 144, 0.6);
--cancel: #b22222;
--cancel-backgound-color: rgba(179, 33, 33, 0.1);
--dark-slate-blue: #483d8b;
--dark-slate-blue-transparent: rgba(72, 61, 139, 0.6);
--dark-slate-grey: #2f4f4f;
--dark-slate-grey-transparent: rgba(47, 79, 79, 0.6);
--disabled: rgba(176, 176, 176, 0.6);
--hover-color: #ffffff;
--loader-color: #00bfff;
--strict: #000000;
--strict-transparent: rgba(0, 0, 0, 0.6);
--teal: #008080;
--teal-transparent: rgba(0, 128, 128, 0.6);
--block-border-radius: 4px;
--block-cancel-padding: 4px;
--block-gap: 6px;
--block-padding: 1px 3px 1px 7px;
--border-radius: 6px;
--border-radius-small: 3px;
--cancel-padding: 3px 8px;
--grid-columns: 1fr 36px 36px;
--grid-rows: 1fr 36px;
--half-size: 50%;
--icon-size-block: 14px;
--icon-size-large: 18px;
--icon-size-medium: 15px;
--icon-size-small: 12px;
--increaser-padding: 3px 7px;
--max-size: 100%;
--min-block-height: 25px;
--options-padding: 6px 0;
--outer-gap: 10px;
--root-padding: 6px 10px;
--toggle-icon-gap: 1px;
--wide-text: 700;
--wrapper-padding: 5px 10px;
--z-index-options: 10;
--border: 1px solid;
--default-cursor: default;
--icons-align-self: center;
--icons-justify-self: center;
--pointer-cursor: pointer;
--wrapper-transition: border-top-left-radius 250ms ease 0s, border-top-right-radius 250ms
ease 0s, border-bottom-left-radius 250ms ease-out, border-bottom-right-radius 250ms
ease-out;You can override it globally or by particular instance class name.
<vue-extended-multiselect class="instance-class" /><style scoped>
.instance-class {
--basic-color: purple;
--outer-gap: 2rem;
--border: 1px dotted;
}
</style>Vue extended multiselect provides following props for customizing:
- errorBorderColor
- iconFilter
- iconSize
- loaderIconFilter
- themeType
- toggleIcon
- anyOptionWrapperBlockHeight
- toggleMaxHeight
- toggleMinHeight
Changing border color when extended multiselect value is invalid.
<vue-extended-multiselect error-border-color="#8B0000" />Changing svg color filter for icons.
<vue-extended-multiselect icon-filter="green" />Resizing icons.
<vue-extended-multiselect icon-size="small" />Changing svg color filter for loader icon.
<vue-extended-multiselect icon-size="small" />Changing general color theme of extended multiselect.
<vue-extended-multiselect theme-type="slate-blue" />Changing toggle icon form.
<vue-extended-multiselect toggle-icon="triangle-arrow" />Resizing option blocks in options list.
<vue-extended-multiselect :any-option-wrapper-block-height="60" />Changing "max-height" css-property of options list.
<vue-extended-multiselect :toggle-max-height="500" />Changing "min-height" css-property of options list.
<vue-extended-multiselect :toggle-min-height="500" />