WpmSelectBox Component

A customizable multiselect dropdown component with search functionality, grouped options, recent searches, and tag display. It supports custom slots for rendering selected items, list items, and recent searches.

Props

| Prop Name | Type | Default | Description | |-------------------------|--------------------|--------------------|----------------------------------------------------------------------------------------------| | modelValue | String/Array/Object/null | Required | The selected value(s) for the multiselect. | | options | Array | Required | The list of options to display in the dropdown. | | groups | Boolean | false | Enables grouping of options in the dropdown. | | closeAfterSelection | Boolean | false | Automatically closes the dropdown after selecting an item. | | multiple | Boolean | false | Enables selecting multiple options. | | placeholder | String | Kam greste? | Placeholder text to display in the input field when no value is selected. | | includedPlaceholder | String | Already included | Text displayed for the section containing already selected items. | | notIncludedPlaceholder| String | Not included | Text displayed for the section containing options that are not yet selected. | | themeColor | String | #1890ff | The primary theme color used for styling the component. | | noResultsText | String | No results found | Text displayed when no matching results are found. | | loading | Boolean | false | Indicates whether the component is in a loading state. | | showClearButton | Boolean | false | Displays a clear button to reset the selected value(s). | | maxSelection | Number | Infinity | Maximum number of items that can be selected. | | minSelection | Number | 0 | Minimum number of items that must be selected. | | maxShow | Number | 0 | Maximum number of options to display at once in the dropdown. | | search | Array/Function | ['id', 'name'] | Specifies the keys or a custom function for searching through the options. | | keyId | String | id | Key used to uniquely identify items in the options list. | | included | Boolean | false | Displays an additional section for already selected items in the dropdown. | | enableGroups | Boolean | false | Enables support for grouped options in the dropdown. | | clearOnSelection | Boolean | false | Clears the search query after selecting an item. | | clearAll | Boolean | false | Displays a clear icon to remove all selected items at once. |

Slots

wsb-selected-tag

Customizes the appearance of selected tags in the component. This slot is displayed for each item in the list of selected items.

• Slot Props:
  • item (Object): The currently selected item.
  • toggleSelection (Function): A method that can be invoked to toggle the selection state of the item.

list-search-item

Customizes the appearance of items in the dropdown search results. Slot props:

• item: The item being displayed in the search results.

list-search-item-name

Customizes the appearance of the name displayed for each item in the dropdown search results.

list-selected-item

Customizes the appearance of selected items displayed in the dropdown. Slot props:

• item: The currently selected item.

list-recent-item

Customizes the appearance of recent search items. Slot props:

• item: The recent item being displayed.

list-group-item

Customizes the appearance of grouped dropdown items. Slot props:

• item: The grouped item being displayed.

wsb-close-indicator

Customizes the appearance of the close or clear icon used to remove all selected items. This slot is typically displayed when there are selected items, allowing users to clear their selection. Slot props:

• removeSelected: A function to be invoked when the close icon is clicked. It clears all selected items.

Events

update:modelValue

Emitted whenever the selected items are updated.

• Payload:
  • Array: An array of selected items, reduced by the reduce function if provided.
• Description:
  • This event is triggered every time the selection changes.
  • It ensures the parent component receives the updated selection state.

toggle:dropdown

Emitted when the dropdown is toggled (opened or closed).

• Payload:
  • Boolean: true if the dropdown is opened, false if it is closed.
• Description:
  • This event indicates the current visibility state of the dropdown.
  • Useful for reacting to the dropdown state in the parent component.

toggle:selection

Emitted when an item is selected or deselected.

• Payload:
  • Boolean: The current visibility state of the dropdown (true or false).
• Description:
  • This event is emitted after an item is added to or removed from the selection.
  • Useful for tracking the dropdown's state after a selection is made.

Example Usage

• Single Select

   <WpmSelectBox theme-color="#b69562"
                 recent-cookie="wsb-destination-recent"
                 :search="['tag','country_name','name']"
                 :options="data"
                 :reduce="e => e.id"
                 :maxShow="10"
                 :recent="true"
                 :included="true"
                 v-model="selectedIDs"
                 :multiple="false"
                 :close-after-selection="true"
                 :clear-all="false"
>
  <template #list-search-item-name="{ item }">
    <span class="d-inline me-2 p-0 my-0">{{ item.flag }}</span>
    <span>{{ item.name }}</span>
    <span v-if="item.country_name">, {{ item.country_name }}</span>
    <span class="wsb-tag" :class="item.tagClass">{{ item.tag }}</span>
  </template>
</WpmSelectBox>

• Multi Select

<WpmSelectBox theme-color="#b69562"
              recent-cookie="wsb-destination-recent"
              :search="['tag','country_name','name']"
              :options="data"
              :reduce="e => e.id"
              :maxShow="10"
              :recent="true"
              :included="true"
              v-model="selectedIDs"
              :multiple="true"
              :close-after-selection="true"
              :clear-on-selection="true"
              :clear-all="false"
>
  <template #list-search-item-name="{ item }">
    <span class="d-inline me-2 p-0 my-0">{{ item.flag }}</span>
    <span>{{ item.name }}</span>
    <span v-if="item.country_name">, {{ item.country_name }}</span>
    <span class="wsb-tag" :class="item.tagClass">{{ item.tag }}</span>
  </template>
</WpmSelectBox>

Slot usage examples

• No Slot usage

<WpmSelectBox theme-color="#b69562"
              recent-cookie="wsb-destination-recent"
              :search="['tag','country_name','name']"
              :options="data"
              :reduce="e => e.id"
              :maxShow="10"
              :recent="true"
              :included="true"
              v-model="selectedIDs"
              :multiple="false"
              :close-after-selection="true"
              :clear-all="false">
</WpmSelectBox>

• Using the wsb-selected-tag Slot

<WpmSelectBox theme-color="#b69562"
              recent-cookie="wsb-destination-recent"
              :search="['tag','country_name','name']"
              :options="data"
              :reduce="e => e.id"
              :maxShow="10"
              :recent="true"
              :included="true"
              v-model="selectedIDs"
              :multiple="false"
              :close-after-selection="true"
              :clear-all="false">
  <template #wsb-selected-tag="{ item, toggleSelection }">
    <div class="custom-selected-tag">
      <span>{{ item.name }}</span>
      <button @click="toggleSelection(item)">Remove</button>
    </div>
  </template>
</WpmSelectBox>

• Multi Select using list-search-item Slot

<WpmSelectBox theme-color="#b69562"
              recent-cookie="wsb-destination-recent"
              :search="['tag','country_name','name']"
              :options="data"
              :reduce="e => e.id"
              :maxShow="10"
              :recent="true"
              :included="true"
              v-model="selectedIDs"
              :multiple="false"
              :close-after-selection="true"
              :clear-all="false">
  <template #list-search-item="{ item }">
    <div class="custom-search-item">
      <span>{{ item.flag }}</span>
      <span>{{ item.name }}</span>,
      <span>{{ item.tag }}</span>
    </div>
  </template>
</WpmSelectBox>

• Using the list-search-item-name Slot

<WpmSelectBox theme-color="#b69562"
              recent-cookie="wsb-destination-recent"
              :search="['tag','country_name','name']"
              :options="data"
              :reduce="e => e.id"
              :maxShow="10"
              :recent="true"
              :included="true"
              v-model="selectedIDs"
              :multiple="false"
              :close-after-selection="true"
              :clear-all="false">
  <template #list-search-item-name="{ item }">
    <span>{{ item.flag }} {{ item.name }}</span>
  </template>
</WpmSelectBox>

• Using the list-selected-item Slot

<WpmSelectBox theme-color="#b69562"
              recent-cookie="wsb-destination-recent"
              :search="['tag','country_name','name']"
              :options="data"
              :reduce="e => e.id"
              :maxShow="10"
              :recent="true"
              :included="true"
              v-model="selectedIDs"
              :multiple="false"
              :close-after-selection="true"
              :clear-all="false">
  <template #list-selected-item="{ item }">
    <div class="custom-selected-item">
      <span>{{ item.name }}</span> 
      <span>({{ item.tag }})</span>
    </div>
  </template>
</WpmSelectBox>

• Using the list-recent-item Slot

<WpmSelectBox theme-color="#b69562"
              recent-cookie="wsb-destination-recent"
              :search="['tag','country_name','name']"
              :options="data"
              :reduce="e => e.id"
              :maxShow="10"
              :recent="true"
              :included="true"
              v-model="selectedIDs"
              :multiple="false"
              :close-after-selection="true"
              :clear-all="false">
  <template #list-recent-item="{ item }">
    <div class="custom-recent-item">
      {{ item.name }} (Recently searched)
    </div>
  </template>
</WpmSelectBox>

• Using the list-group-item Slot

<WpmSelectBox theme-color="#b69562"
              recent-cookie="wsb-destination-recent"
              :search="['tag','country_name','name']"
              :options="data"
              :reduce="e => e.id"
              :maxShow="10"
              :recent="true"
              :included="true"
              v-model="selectedIDs"
              :multiple="false"
              :close-after-selection="true"
              :clear-all="false">
  <template #list-group-item="{ item }">
    <div class="custom-group-item">
      {{ item.name }} (Grouped)
    </div>
  </template>
</WpmSelectBox>

• Using the wsb-close-indicator Slot

<WpmSelectBox theme-color="#b69562"
              recent-cookie="wsb-destination-recent"
              :search="['tag','country_name','name']"
              :options="data"
              :reduce="e => e.id"
              :maxShow="10"
              :recent="true"
              :included="true"
              v-model="selectedIDs"
              :multiple="false"
              :close-after-selection="true"
              :clear-all="true">
  <template #wsb-close-indicator="{ removeSelected }">
    <button @click="removeSelected" class="custom-clear-btn">Clear All</button>
  </template>
</WpmSelectBox>