vue-combo-blocks v2.1.1

Vue Combo Blocks 🧱

Provides all the building blocks needed for accessible autocomplete, combobox, or typeahead component.

A very Downshift like autocomplete solution for Vue

Downshift for Vue.js

The problem

You want to build an autocomplete/combobox component, and it needs to be accessible, lightweight and you don't really want extra dependencies or styling you would not use, or you'd have to hack around to to make it your own.

The solution

This library provides you the state and the controls for your combobox. You provide the elements and styles to build the thing you need.

Installation

For vue 3.x use npm i vue-combo-blocks For vue 2.x use npm i vue-combo-blocks@vue2

Usage

Try it out in codesandbox

<template>
  <vue-combo-blocks
    v-model="selected"
    :itemToString="itemToString"
    :items="filteredList"
    @input-value-change="updateList"
    v-slot:default="{
      getInputProps,
      getInputEventListeners,
      hoveredIndex,
      isOpen,
      getMenuProps,
      getMenuEventListeners,
      getItemProps,
      getItemEventListeners,
      getComboboxProps,
      reset,
    }"
  >
    <div v-bind="getComboboxProps()">
      <button @click="reset">reset</button>
      <input
        v-bind="getInputProps()"
        v-on="getInputEventListeners()"
        placeholder="Search"
      />
      <ul
        v-show="isOpen"
        v-bind="getMenuProps()"
        v-on="getMenuEventListeners()"
      >
        <li
          v-for="(item, index) in filteredList"
          :key="item.id"
          :style="{
            backgroundColor: hoveredIndex === index ? 'lightgray' : 'white',
            fontWeight: selected === item ? 'bold' : 'normal',
          }"
          v-bind="getItemProps({ item, index })"
          v-on="getItemEventListeners({ item, index })"
        >
          {{ item.value }}
        </li>
      </ul>
    </div>
  </vue-combo-blocks>
</template>

<script>
import VueComboBlocks from 'vue-combo-blocks';

// This list could come from an external api
const list = [
  { value: 'Gretsch', id: '1' },
  { value: 'Ludwig', id: '2' },
  { value: 'Mapex', id: '3' },
  { value: 'Pearl', id: '4' },
  { value: 'Sonor', id: '5' },
  { value: 'Tama', id: '6' },
  { value: 'Zildjian', id: '7' },
];
export default {
  components: {
    VueComboBlocks,
  },
  data() {
    return {
      selected: null,
      filteredList: list,
    };
  },
  methods: {
    itemToString(item) {
      return item ? item.value : '';
    },
    // This could be a call to an api that returns the options
    updateList(text) {
      this.filteredList = list.filter((item) =>
        item.value.toLowerCase().includes(text.toLowerCase()),
      );
    },
  },
};
</script>

Props

Events

Emitted events return 2 parameters. First is the new value, and second is the state change type.

Default Slot & returned props

Default slot's scope contains: prop getters, event listeners, component state and actions.

Prop getters

Bind the prop getters to their elements with v-bind and event listeners with v-on. You can add your own event listeners to these elements too and any other props needed.

<input v-bind="getInputProps()" v-on="getInputEventListeners()" />

Event listeners

Custom Event Listeners

(New in 1.1.0)

You can add custom event listers with default event listeners. Your custom event listener will run before vue-combo-blocks internal event listener:

<vue-combo-blocks
  v-slot:default="{
    getInputProps,
    getInputEventListeners,
  }"
>
  <input v-bind="getInputProps()" v-on="getInputEventListeners()" @input="myInput" />
</vue-combo-blocks>

You can also override, or just prevent the default event by providing you custom event listener as an argument:

<vue-combo-blocks
  v-slot:default="{
    getInputProps,
    getInputEventListeners,
  }"
>
    <input v-bind="getInputProps()" v-on="getInputEventListeners({ input: myInput })" />
  </vue-combo-blocks>

State

Actions

State Reducer

function(state: object, actionAndChanges: object This function is called each time vue-combo-blocks sets its internal state. It gives you the current state and the state that will be set, and you return the state that you want to set.

• state: The full current state of vue-combo-blocks.
• actionAndChanges: Object that contains the action type, props needed to return a new state based on that type and the changes suggested by the vue-combo-blocks default reducer. About the type property you can learn more about in the stateChangeTypes section.

In this example, we want to keep the menu open after the item is selected, and keep the input value empty

<template>
  <vue-combo-blocks :stateReducer="stateReducer" ****>
    ****
  </vue-combo-blocks>
</template>

  methods: {
    stateReducer(oldState, { changes, type }) {
      switch (type) {
        case VueComboBlocks.stateChangeTypes.InputKeyUpEnter:
        case VueComboBlocks.stateChangeTypes.ItemClick:
          return {
            ...changes,
            isOpen: true,
            inputValue: '',
          };
        default:
          return changes;
      }
    },
  }

stateChangeTypes

The list of all possible values this type property can take is defined in this file and is as follows:

• VueComboBlocks.stateChangeTypes.InputKeyDownArrowDown
• VueComboBlocks.stateChangeTypes.InputKeyDownArrowUp
• VueComboBlocks.stateChangeTypes.InputKeyDownTab
• VueComboBlocks.stateChangeTypes.InputKeyUpEscape
• VueComboBlocks.stateChangeTypes.InputKeyUpEnter
• VueComboBlocks.stateChangeTypes.InputChange
• VueComboBlocks.stateChangeTypes.InputBlur
• VueComboBlocks.stateChangeTypes.MenuMouseLeave
• VueComboBlocks.stateChangeTypes.ItemMouseMove
• VueComboBlocks.stateChangeTypes.ItemClick
• VueComboBlocks.stateChangeTypes.FunctionOpenMenu
• VueComboBlocks.stateChangeTypes.FunctionCloseMenu
• VueComboBlocks.stateChangeTypes.FunctionSelectItem
• VueComboBlocks.stateChangeTypes.FunctionSetInputValue
• VueComboBlocks.stateChangeTypes.FunctionReset
• VueComboBlocks.stateChangeTypes.ControlledPropUpdatedSelectedItem