Vue GridMultiSelect Tutorial and Quick Guide
Tags: webdev, javascript, vue, opensource
Published: 2019-12-17 14:11:28

---
title: Vue GridMultiSelect Tutorial and Quick Guide
published: true
description: Vue GridMultiSelect Tutorial - Simple multi-select component with items displayed in a table like UI
tags: #webdev, #javascript, #vue, #opensource
---

> Originally posted on [devinduct](https://devinduct.com/blogpost/53/vue-gridmultiselect-tutorial-and-quick-guide)

## Table of Contents

- [What is vue-gridmultiselect](#what-is-vue-gridmultiselect)
- [Basic Usage](#basic-usage)
- [Labeling](#labeling)
- [Grouping](#grouping)
- [Slots and Row Details](#slots-and-row-details)
- [Menu Position](#menu-position)
- [Live Demo](#demo)
- [Conclusion and Further Reading](#conclusion-and-further-reading)

## What is Vue GridMultiselect

![img](https://raw.githubusercontent.com/ProticM/vue-gridmultiselect/master/cover-img.jpg)

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](https://github.com/ProticM/vue-gridmultiselect)
- [Examples and Demos](https://proticm.github.io/vue-gridmultiselect/guide/examples.html#minimum-configuration)

## Basic Usage

Step 1 - Installation

```js
npm install vue-gridmultiselect --save
```

Step 2 - Register a component with GridMultiSelect in the template

HTML

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

JS

```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](https://proticm.github.io/vue-gridmultiselect/guide/) 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](https://proticm.github.io/vue-gridmultiselect/guide/examples.html#minimum-configuration) 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.

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

To read more about labeling, see [official documentation](https://proticm.github.io/vue-gridmultiselect/guide/examples.html#labeling).

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

```html
<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](#demo), our side list is grouped by the state item property. To read more about grouping, see [official documentation](https://proticm.github.io/vue-gridmultiselect/guide/examples.html#grouping).

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

```html
<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](#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:

```html
<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:

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

{% codepen https://codepen.io/protic_milos/pen/vYEKywq %}

## 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](https://github.com/ProticM/vue-gridmultiselect). For more in-depth explanations, visit the [official documentation website](https://proticm.github.io/vue-gridmultiselect/).

To stay tuned do subscribe on devinduct, or follow me on [twitter](https://twitter.com/protic_milos).

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