@singularit/multiselect

sIT Multiselect Komponente

• Installation
• Props
• Events
• Slots
• Styling
  • Default Tailwind Classes
  • Customization
• Examples
  • Single Select
  • Multiselect

Installation

npm install @singularit/multiselect

Props

Name	Type	Default	Description
modelValue	string|number|object|array|boolean	null|[]	The value that is used externally. The default values make sure the component works if the the selected values aren't used externally.
multiple	boolean	false	Whether multiple options can be selected.
selectOptions	array	[]	Array of options that can be selected. An option should look like this: {value: ..., label: '...', ...}.
placeholder	string	''	The placeholder string will be displayed if no option is selected.
optionLabel	function		Function that determines which attribute of the option object should be displayed as label. The passed parameters are an option and an array of all selected options. By default, it returns the label attribute of the passed option.
optionValue	function		Function that determines which attribute of the option object should be used as value. Passes an option as parameter. By default, it returns the value attribute of the passed option.
optionDisabled	function		Function which determines if an option is disabled. The passed parameters are an option and an array of all selected options. By default, it returns the disabled attribute of the passed option.
displaySelectedValues	function|string		Determines what is displayed in the value display. Can be a string or a function returning a string. The passed parameter of the function is an array of all selected options. By default the amount of selected options will be displayed in multiselect and the optionValue of an option in single select.
clearable	boolean	true	Whether all selected options can be cleared.
disabled	boolean	false	Disables the component. Values can still be pushed into the model value externally.
searchable	boolean	false	Whether options can be searched.
searchProps	object		Allows passing HTML input attributes to the search input element.
optionSearchValue	function		Determines which value of the option Object is searched. It is a function which returns the value of an option that is tracked by the search input. Passes an option as parameter. By default, it returns the label of the passed option.
selectProps	object		Allows passing HTML select attributes to the hidden select element.
closeOnSelect	boolean	false	Whether the selection dropdown should automatically be closed after selecting/deselection an option.
noOptionsText	string	'Die Liste ist leer'	Text that is displayed if no options are given.
noResultsText	string	'Keine Ergebnisse gefunden'	Text that is displayed if there are no search results.
classes	object	{}	An object of class names that gets merged with the default values.
infinite	boolean	false	When set to true, loadMore will be emitted if you scroll to the bottom of the option dropdown.
maxOptions	number	1000	Is the maximum amount of options for infinite scrolling. If it is reached loadMore won't be emitted when scrolling to the bottom of the dropdown while infinite is true.
loadingOptions	boolean	false	Whether the options are loading. Displays a loading spinner in the dropdown if set to true.

Events

Event	Attributes	Description
@open		Emitted after opening the selection dropdown.
@close		Emitted after closing the selection dropdown.
@select	option	Emitted after an option is selected.
@deselect	option	Emitted after an option is deselected.
@search-change	query	Emitted after a character is typed in the search input.
@clear		Emitted after selected options are cleared.
@loadMore		Emitted after scrolling to the bottom of the option dropdown while infinite is true.

Slots

Slot	Attributes	Description
placeholder		Rendered as placeholder when no option is selected and placeholder prop is defined.
value-display	selectedOptions	Rendered if an option is selected and the search input is empty.
option-label	option,isSelected	Renders an option in the selection dropdown. isSelected is provided to determine the state.
clear	clear	Renders a remove icon if any option is selected and clearable prop is true. The clear method should be used on @mousedown event.
no-options		Rendered if the options list is empty. By default renders noOptionsText.
no-results		Rendered if there are no search results. By default renders noResultsText.
loading-options		Rendered in option dropdown if loadingOptions is true.

Styling

Default Tailwind Classes

These are the default Tailwind classes used for styling the component.

{
    container: 'h-auto relative mx-auto w-full flex items-center justify-end box-border cursor-pointer border border-gray-300 bg-white rounded text-base leading-snug outline-none',
    containerDisabled: 'cursor-default',
    containerOpen: 'rounded-b-none',
    containerActive: 'ring ring-opacity-70 ring-orange-400',
    label: 'flex items-center h-full absolute left-0 top-0 pointer-events-none bg-transparent leading-snug pl-3.5',
    search: 'w-full absolute inset-0 outline-none appearance-none box-border border-0 text-base font-sans bg-white rounded pl-3.5',
    placeholder: 'flex items-center h-full absolute left-0 top-0 pointer-events-none bg-transparent leading-snug pl-3.5 text-gray-400',
    clear: 'pr-3.5 relative z-10 opacity-40 transition duration-300 flex-shrink-0 flex-grow-0 flex hover:opacity-80',
    clearIcon: 'text-lg font-bold text-center pl-3',
    dropdown: 'max-h-60 absolute -left-px -right-px bottom-0 transform translate-y-full border border-gray-300 -mt-px overflow-y-auto z-50 bg-white flex flex-col rounded-b',
    dropdownHidden: 'hidden',
    options: 'flex flex-col p-0 m-0 list-none',
    option: 'flex items-center justify-start box-border text-left cursor-pointer text-base leading-snug py-2 px-3 hover:text-gray-800 hover:bg-gray-100',
    optionSelected: 'text-white bg-orange-400 hover:bg-orange-500',
    optionDisabled: 'flex items-center justify-start box-border text-left text-base leading-snug py-2 px-3 bg-gray-200 cursor-disabled',
    noOptions: 'py-2 px-3 text-gray-600 bg-white text-left rtl:text-right',
    noResults: 'py-2 px-3 text-gray-600 bg-white text-left rtl:text-right',
    spacer: 'h-9 py-px box-content',
}

Customization

If you want to completely re-style some elements from ground up:

<Multiselect
    ...
    :classes="{
        container: 'some new tailwind classes',
        ...
    }"
/> 

If you just want to keep the recommended base style an only change a few things like colors or sizes, import baseStyle and use it like this:

<Multiselect ... 
    :classes="{
        container: [baseStyle.container, 'bg-gray-200'],
        spacer: [baseStyle.spacer, 'h-20'],
        dropdown: [baseStyle.dropdown, 'max-h-90'],
        optionSelected: [baseStyle.optionSelected, 'bg-gray-400 hover:bg-gray-500'],
        ... 
        }"
/>

Examples

Single select

<Multiselect
  v-model="value"
  :select-options="[
      {value: 'Just', label: 'How'},
      {value: 'an', label: 'are'},
      {value: 'example', label: 'you?'}
  ]"
/>

Multiselect

<Multiselect
  v-model="value"
  multiple
  :select-options="[
      {value: 'Just', label: 'How'},
      {value: 'an', label: 'are'},
      {value: 'example', label: 'you?'}
  ]"
/>