Vue GridMultiSelect Tutorial and Quick Guide

Originally posted on devinduct

Table of Contents

• What is vue-gridmultiselect
• Basic Usage
• Labeling
• Grouping
• Slots and Row Details
• Menu Position
• Live Demo
• Conclusion and Further Reading

What is Vue GridMultiselect

It's a simple component that gives you the ability to select items and display them in a table-like UI. Like a dropdown list but a little different. It requires minimal setup (single module installation) supporting the V-model and Vuex out of the box.

The component can be easily customized and turned from a simple read-only list into a grid with custom header and footer, clickable rows with details showing the data from a groupable and searchable data source...and more. Stay tuned.

Core Features and Characteristics:

• No dependencies
• Searching
• Grouping
• Disabling Items
• Row Details
• Easily configurable
• Custom slots
• Menu Positioning
• V-model support
• Vuex support

Useful links:

• GitHub
• Examples and Demos

Basic Usage

Step 1 - Installation

npm install vue-gridmultiselect --save

Step 2 - Register a component with GridMultiSelect in the template

HTML

<template>
  <GridMultiSelect 
    :items="items" 
    item-key="id" 
    item-label="name" 
    v-model="selectedItems" 
  />
</template>

JS

import GridMultiSelect from 'vue-gridmultiselect';
import 'vue-gridmultiselect/dist/vue-gridmultiselect.css';

export default {
  name: "example",
  components: { GridMultiSelect },
  data() {
    return {
      selectedItems: null,
      items: [
        { id: 1, name: "San Francisco", state: "USA", info: "San Francisco information" },
        { id: 2, name: "Las Vegas", state: "USA", info: "Las Vegas information" },
        { id: 3, name: "Washington", state: "USA", info: "Washington information" },
        { id: 4, name: "Munich", state: "Germany", info: "Munich information" }
      ]
    };
  }
};

And you are set! The component is ready. See here how to register and install via CDN.

Item key and item label are required properties. Item key is passed on to the Vue framework (:key directive) and it must be unique because based on that value the framework will handle the component updates. Item label represents the value we want to be displayed as text within each item in the list/s. Item label can be a String or an Array. See docs for more information.

Ok, now when we know what is the minimum configuration we can spice it up a little bit.

Labeling

Each item label is customizable, both in items and the selected items list by using the item-label property. This property accepts a String or an Array. With an array, we can control the labels of both lists in the component. Each item in the given array can hold the property names combination, for example, name|state.

Also, we can set the component title label by using the title property.

Let's update our example component template to reflect this.

<GridMultiSelect 
  :items="items" 
  item-key="id" 
  :item-label="['name', 'name|state']"
  v-model="selectedItems" 
  title="Cities" 
/>

To read more about labeling, see official documentation.

Grouping

The items list can contain groups. To enable grouping you need to provide one additional property which will tell the component by what value to group the data source collection. The property name is group-by

Do note that at this point, you cannot group the selected items list

Let's update the component template.

<GridMultiSelect 
  :items="items" 
  item-key="id" 
  :item-label="['name', 'name|state']" 
  v-model="selectedItems" 
  title="Cities"
  group-by="state"
/>

Now, as shown in the demo, our side list is grouped by the state item property. To read more about grouping, see official documentation.

Slots and Row Details

Selected items can be shown together with a certain amount of details. To achieve this, the component property item-details should be set. This property should hold the key from the items collection and by setting it up we are saying to the component from where to read each item details. This property accepts a String and it can hold the key combinations, just like the item-label prop. Let's update our template.

<GridMultiSelect 
  :items="items" 
  item-key="id" 
  :item-label="['name', 'name|state']" 
  v-model="selectedItems" 
  title="Cities"
  group-by="state"
  item-details="info"
/>

Now, our grid becomes accordion and we can expand each row as shown in the demo. For example, if we expand the first row, we should see San Francisco information text in the details section.

Ok, now we need some buttons at the bottom of the grid. We can easily achieve this by using the selected-items-footer slot as follows:

<GridMultiSelect 
  :items="items" 
  item-key="id" 
  :item-label="['name', 'name|state']" 
  v-model="selectedItems" 
  title="Cities"
  group-by="state"
  item-details="info"
>
  <template v-slot:selected-items-footer>
    <div class="buttons">
      <button @click="save">Save</button>
      <button @click="cancel">Cancel</button>
    </div>
  </template>
</GridMultiSelect>

Menu Position

By default, the component menu is docked to the right. This can be adjusted with the menu-position property. The value can be dock which is the default, or float. The updated and final demo template looks like this:

<GridMultiSelect 
  :items="items" 
  item-key="id" 
  :item-label="['name', 'name|state']" 
  v-model="selectedItems" 
  title="Cities"
  group-by="state"
  item-details="info"
  menu-position="float"
>
  <template v-slot:selected-items-footer>
    <div class="buttons">
      <button @click="save">Save</button>
      <button @click="cancel">Cancel</button>
    </div>
  </template>
</GridMultiSelect>

Demo

Conclusion and Further Reading

This was a quick introduction to the Vue GridMultiselect component. If you like what you see please give it a star on GitHub. For more in-depth explanations, visit the official documentation website.

To stay tuned do subscribe on devinduct, or follow me on twitter.

Thank you for reading and see you in the next article.