vue3-extended-multiselect

v3.0.3

Published

3 months ago

Extended multiselect dropdown component for Vue 3 with search, tagging, async options and flexible customization.

0High
0Medium
0Low

danyaridiger

multiselect select extended vue vue3 component dropdown form

vue3-extended-multiselect v3.0.2

Brief annotation

vue3-extended-multiselect is a component designed to simplify the custom configuration of the built-in select element. By leveraging its built-in themes, this component allows developers to avoid writing extensive CSS rules. It also eliminates common issues associated with handling different types of option data.

The component enhances the options list with various decorative slots, enabling developers to create a more informative and intuitive interface. Furthermore, it performs thorough filtering on the raw options list provided by the developer, preventing unexpected errors from unintended option formats. Switchable, helpful warnings assist in identifying potential errors during development.

For user convenience, the component includes tools to manage selected options, controlling the number displayed and allowing for quick deselection. Developers can also customize these tools to fit their specific needs. With various slots available, developers can freely customize the options list, the selected tags in multiple-select mode, and other interactive elements.

You can integrate this component into your web applications built with the Vue 3 framework.**

Page with live examples

https://vue3-extended-multiselect.surge.sh/

Installation with npm

npm install vue3-extended-multiselect

Installation with yarn

yarn add vue3-extended-multiselect

Installation with pnpm

pnpm add vue3-extended-multiselect

Importing

import Vue3ExtendedMultiselect from "vue3-extended-multiselect";

Importing types

import type { UnionOptionType } from "vue3-extended-multiselect";

Usage with UMD

Somewhere in your markup...

<script src="./public/scripts/vue3-extended-multiselect/index.umd.js"></script>

Somewhere in your script below...

const YourComponent = defineComponent({
  name: "YourComponent",
  components: {
    Vue3ExtendedMultiselect: window.Vue3ExtendedMultiselect,
  },
});

Props list

| Prop name | Prop type | Prop appointment | Prop default value | Prop values | | ----------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | autoSelectCreatedOption | Boolean | Determines whether to select just now created option automatically. | false | — | | autoSelectSearchValue | Boolean | Determines whether to take search value from current selected option if "multiple" prop equals false. | false | — | | clearBySelectWhenMultiple | Boolean | Determines whether to clear search field by option selection. | false | — | | createOnTheGo | Boolean | Allows user to create new options from search field. | false | — | | defaultExpanded | Boolean | Determines whether options list should be expanded by default. | false | — | | disabled | Boolean | Disables extended multiselect. | false | — | | dropdownDisabled | Boolean | Disables dropdown toggle. | false | — | | highlightOptions | 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 | — | | noResultsBlockShown | Boolean | Determines whether to show special hint if no options were found. | true | — | | resetSearchByValue | Boolean | Determines whether to clear search field by selection/deselection of options. | true | — | | searchFilterActive | Boolean | Allows user to use internal search for options. | true | — | | simpleEvents | Boolean | Switches full payload of extended multiselect events. | true | — | | selectedOptionsShown | Boolean | Determines whether to show selected options in options list. | false | — | | showClearIcon | Boolean | Allows user to deselect all options by special icon. | false | — | | showDeselectIconLoader | Boolean | Determines whether to show loader icon in multiple options block if "loading" prop equals true | true | — | | showInsertWarnings | 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 | — | | showSearchField | Boolean | Determines whether to show search field which allows user to search for options with internal search. | true | — | | toggleMultipleBlocksLimit | Boolean | Allows user to increase limit of shown elements with selected options by special icon. | false | — | | toggleOptionsBySelect | Boolean | Determines whether to roll up options list by selection of option. | true | — | | togglingSavesSearchValue | Boolean | Determines whether to save current search value if display of options list was toggled. | true | — | | wrongCurrentValue | Boolean | Determines whether to define special class for extended multiselect if value is wrong or if irregularity of value is defined by user. | false | — | | createOptionPlaceholder | String | Placeholder for the search field to be used if user is allowed to create new options. | "Select or create features" | — | | createOptionType | 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" | — | | emptyObjectsPlaceholder | String | Placeholder for options of type "object" or Array instances which length/keys length equals 0. | "Empty Object/Array" | — | | errorBorderColor | 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" | — | | loaderIconFilter | 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" | | toggleAppearanceSide | 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" | | anyOptionWrapperBlockHeight | Number | Defines "height" css-property for each option in options list. | 30 | — | | increaseDisplayBy | Number | Defines gap which increases limit of displayed elements with selected options. | 5 | — | | maxOptionsCount | Number | Maximal limit of selected options. | null | — | | minOptionsCount | Number | Minimal limit of selected options. | null | — | | multipleBlocksLimit | Number | Defines limit of displayed elements with selected options. | null | — | | optionsCountRestriction | Number | Defines maximal limit of options list length. | null | — | | toggleMaxHeight | Number | Defines maximal value in pixels of "max-height" css-property for options list. | 400 | — | | toggleMinHeight | Number | Defines minimal value in pixels of "max-height" css-property for options list. | null | — | | createOptionFields | Array | Defines a list of fields for options of type "object" created by user. | ["label"] | — | | disabledPrimitiveOptions | 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. | [] | — | | preselectedOptions | Array | Defines a list of options that will be select by default. | [] | — | | specialKeysBlock | Array | Defines a list of keys which in combination with mouse buttons or "enter" key will prevent selection of option. | [] | "alt", "ctrl", "shift" | | createCustomOptionLabel | Function | Defines function that creates custom label for each option. | (option) => null | — | | multipleBlocksLimitMessage | 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 | — | | preselectedOption | 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". | [] | — |

Slots list

| 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 |

Events list

| 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 |

Styling with css

Vue3 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.

<vue3-extended-multiselect class="instance-class" />

<style scoped>
  .instance-class {
    --basic-color: purple;
    --outer-gap: 2rem;
    --border: 1px dotted;
  }
</style>

Styling with props

Vue3 extended multiselect provides following props for customizing:

errorBorderColor
iconFilter
iconSize
loaderIconFilter
themeType
toggleIcon
anyOptionWrapperBlockHeight
toggleMaxHeight
toggleMinHeight

Customizing examples

Changing border color when extended multiselect value is invalid.

<vue3-extended-multiselect error-border-color="#8B0000" />

Changing svg color filter for icons.

<vue3-extended-multiselect icon-filter="green" />

Resizing icons.

<vue3-extended-multiselect icon-size="small" />

Changing svg color filter for loader icon.

<vue3-extended-multiselect icon-size="small" />

Changing general color theme of extended multiselect.

<vue3-extended-multiselect theme-type="slate-blue" />

Changing toggle icon form.

<vue3-extended-multiselect toggle-icon="triangle-arrow" />

Resizing option blocks in options list.

<vue3-extended-multiselect :any-option-wrapper-block-height="60" />

Changing "max-height" css-property of options list.

<vue3-extended-multiselect :toggle-max-height="500" />

Changing "min-height" css-property of options list.

<vue3-extended-multiselect :toggle-min-height="500" />

License

MIT