1. vue-bootstrap4-table

> Advanced table based on Vue 2 and Bootstrap 4

Quick Demo in Codepen.

Docs in gitbook.

2. Features

• Multi column filtering (Optimized filtering)
  • Simple filter
  • Select filter (Single & Multiple)
• Global search
• Single & Multi column sorting
• Pagination (True! It works out of the box intelligently)
• Pagination Information
• Checkbox selection for rows
• Client & Server mode
• Highly customizable

Table of Contents

• 1. vue-bootstrap4-table
• 2. Features
• 3. Installation
  • 3.1. Install via npm or yarn
    • 3.1.1. Dependencies
  • 3.2. Install via CDN
• 4. Basic Usage
• 5. Columns
  • 5.1. Basic structure
  • 5.2. Attributes details
  • 5.3. Column slot
    • 5.3.1. Example
    • 5.3.2. Note
    • 5.3.3. props
• 6. Rows
  • 6.1. Basic structure
  • 6.2. Row Slot
    • 6.2.1. Example
    • 6.2.2. Note
    • 6.2.3. props
  • 6.3. Empty result message slot
    • 6.3.1. Example
• 7. Sorting
  • 7.1. Example
  • 7.2. Attributes details
  • 7.3. Single column sorting
  • 7.4. Multi column sorting
    • 7.4.1. Example
  • 7.5. Slot
    • 7.5.1. Sort Icon
      • 7.5.1.1. Example
• 8. Filtering
  • 8.1. Simple Filter
    • 8.1.1. Example
    • 8.1.2. Attributes details
    • 8.1.3. Clear button icon slot
  • 8.2. Multi-Select Filter
    • 8.2.1. Example (Single select)
    • 8.2.2. Example (Multi select)
    • 8.2.3. Attribute details
• 9. Global search
  • 9.1. Example
  • 9.2. Attributes details
  • 9.3. Clear button icon slot
• 10. Pagination & Info
  • 10.1. Example
  • 10.2. Attributes details
  • 10.3. Slot
    • 10.3.1. Previous & Next button
    • 10.3.2. Pagination info
      • 10.3.2.1. props
    • 10.3.3. Selected rows info
      • 10.3.3.1. props
• 11. Refresh and Reset button
  • 11.1. Refresh Button
    • 11.1.1. Example
  • 11.2. Reset button
  • 11.3. Slots
    • 11.3.1. Button text and icons
      • 11.3.1.1. Example
• 12. Custom action buttons
  • 12.1. Example
  • 12.2. Attributes details
• 13. Custom classes
  • 13.1. Example
• 14. vbt-classes
  • 14.1. vbt-row-selected
  • 14.2. vbt-table-wrapper
• 15. Config
  • 15.1. Example
  • 15.2. Attributes details
• 16. Server mode
  • 16.1. Example
    • 16.1.1. Step 1
    • 16.1.2. Step 2
    • 16.1.3. Step 3
    • 16.1.4. Step 4
    • 16.1.5. Note
• 17. Events
  • 17.1. on-select-row
    • 17.1.1. Payload (Object)
  • 17.2. on-all-select-rows
    • 17.2.1. Payload (Object)
  • 17.3. on-unselect-row
    • 17.3.1. Payload (Object)
  • 17.4. on-all-unselect-rows
    • 17.4.1. Payload (Object)
  • 17.5. refresh-data
• 18. Build Setup

3. Installation

3.1. Install via npm or yarn

$ npm i vue-bootstrap4-table --save

$ yarn add vue-bootstrap4-table

Currently this package will install only the vue-bootstrap4-table component, not their dependencies. So make sure to install the following dependencies.

3.1.1. Dependencies

• bootstrap 4 (js and css) You should include bootstrap before vue-bootstrap4-table plugin.

We are using lodash internally, so you don't need to install separately for this plugin.

3.2. Install via CDN

...






...

Note: If you've included bootstrap & jQuery packages already in your project, then include only vue-bootstrap4-table.min.js script.

4. Basic Usage

It is easy to include vue-bootstrap4-table as a component in your application.

Import VueBootstrap4Table component in any of your vue component and start using it right away.

Note: If you included the library via CDN, then you don't need to import, you can use vue-bootstrap4-table component right away.

rows and columns props should be passed down to vue-bootstrap4-table component to work with the table.

<template>
    <div id="app">
        
        
    </div>
</template>

5. Columns

5.1. Basic structure

For example, your "columns" object might look like this,

columns: [{
        label: "id",
        name: "id",
        filter: {
            type: "simple",
            placeholder: "Enter id"
        },
        sort: true,
        uniqueId: true
    },
    {
        label: "First Name",
        name: "name.first_name", // access nested objects properties with "."
        filter: {
            type: "simple",
            placeholder: "Enter first name",
            case_sensitive: true, // "false" by default
        },
        sort: true, // "false" by default
        initial_sort: true, // "false" by default
        initial_sort_order: "desc" // "asc" by default
    },
    {
        label: "Email",
        name: "email",
        sort: true,
        row_text_alignment:  "text-left",
        column_text_alignment:  "text-left",
        row_classes:  "my-row-class1 my-row-class2",
        column_classes:  "my-column-class1 my-column-class2"
    },
    {
        label: "Country",
        name: "address.country", // access nested objects properties with "."
        filter: {
            type: "simple",
            placeholder: "Enter country"
        },
        visibility: false
    }]

5.2. Attributes details

5.3. Column slot

At some point, you might want to override or format the values in the column header. vue-bootstrap4-table allow you to achieve that with the help of vue slotting.

5.3.1. Example

...

    <template slot="column_email">
        <i>
            {{props.column.label}}
        </i>
    </template>
    <template slot="column_name_first_name">
        <b>
            {{props.column.label}}
        </b>
    </template>

...

Column slot name will be combination of column_ keyword with the name which you provided in the columns configuration. In the above example, slot="column_email" represents the "email" column header in the table.

5.3.2. Note

You might have some columns with nested objects names. In that case, the slot name will be column_ keyword + column name and dots(.) in the column name will be replaced by underscore(_).

You can see the above example, slot name for name.first_name column is column_name_first_name.

5.3.3. props

From slot-scope="props" you can access the following attributes.

6. Rows

You bind your list of items as array of objects to rows props to vue-bootstrap4-table component, then voilà.. you can start work with the table.

6.1. Basic structure

rows: [{
        "id": 1,
        "name": {
            "first_name": "Vladimir",
            "last_name": "Nitzsche"
        },
        "address": {
            "country": "Mayotte"
        },
        "email": "franecki.anastasia@gmail.com",
    },
    {
        "id": 2,
        "name": {
            "first_name": "Irwin",
            "last_name": "Bayer"
        },
        "age": 23,
        "address": {
            "country": "Guernsey"
        },
        "email": "rlittle@macejkovic.biz",
    },
    {
        "id": 3,
        "name": {
            "first_name": "Don",
            "last_name": "Herman"
        },
        "address": {
            "country": "Papua New Guinea"
        },
        "email": "delia.becker@cormier.com",
    }]

6.2. Row Slot

At some point, you might want to override or format the values in the row cells. vue-bootstrap4-table allow you to achieve that with the help of vue slotting.

6.2.1. Example

...

    <template slot="email">
        <i>
            {{props.cell_value}}
        </i>
    </template>
    <template slot="name_first_name">
        <b>
            {{props.cell_value}}
        </b>
    </template>
    <template slot="lastname">
        <b>
            {{props.cell_value}}
        </b>
    </template>

...

Slot name will be same as the name which you provided in the columns configuration. In the above example, slot="email" represents the "email" column in the table.

6.2.2. Note

You might have some columns getting the values from nested objects from rows. In that case, the slot name will be column name and dots(.) in the column name will be replaced by underscore(_).

You can see the above example, slot name for name.first_name column is name_first_name.

If you don't like this default "slot name" assignment, then you can set names to row slots as shown in the above example.

6.2.3. props

From slot-scope="props" you can access the following attributes.

6.3. Empty result message slot

If the given rows data is empty or result set is empty after applying filters, vue-bootstrap4-table shows this default message "No results found". You can override the message as like your wish with the help of empty-results slot.

6.3.1. Example

...

    <template slot="empty-results">
        Users not found
    </template>

...

7. Sorting

Sorting configuration is added along with the each column config.

7.1. Example

...
columns: [
    {
        label: "First Name",
        name: "name.first_name", // access nested objects properties with "."
        sort: true, // "false" by default
        initial_sort: true, // "false" by default
        initial_sort_order: "desc", // "asc" by default
        sortCaseSensitive: false // "true" by default
    }
]
...

7.2. Attributes details

7.3. Single column sorting

By default single column sort mode is enabled.

7.4. Multi column sorting

If you would like to enable the multi column sorting, set multi_column_sort to true in table config props.

7.4.1. Example

<template>
    <div id="app">
        
        
    </div>
</template>

7.5. Slot

7.5.1. Sort Icon

You can change the sort icons based on your choice, For example if you're using font-awesome or glyphicon in your application, you can still use them for vue-bootstrap4-table.

You can inject your favorite sort icons via slots.

7.5.1.1. Example

...

    <template slot="sort-asc-icon">
        <i class="fas fa-sort-up"></i>
    </template>
    <template slot="sort-desc-icon">
        <i class="fas fa-sort-down"></i>
    </template>
    <template slot="no-sort-icon">
        <i class="fas fa-sort"></i>
    </template>

...

After applying the above custom template to sort icons , output will look like this.

Custom sort icons

8. Filtering

Filtering configuration is added along with the each column config.

8.1. Simple Filter

Filter the rows based on the given keyword. If you don't specify filter config then filter feature will be disabled for the specific column.

8.1.1. Example

...
columns: [
    {
        label: "First Name",
        name: "name.first_name", // access nested objects properties with "."
        filter: {
            type: "simple",
            placeholder: "Enter first name",
            case_sensitive: true, // "false" by default
            showClearButton: false,
            filterOnPressEnter: false,
            debounceRate: 1000,
            init: {
                value : "Christin"
            }
        }
    }
]
...

8.1.2. Attributes details

8.1.3. Clear button icon slot

You can override the default clear button icon in the simple filter text input.

...

    <template slot="simple-filter-clear-icon">
        <i class="fas fa-times-circle"></i>
    </template>

...

8.2. Multi-Select Filter

You can have multi select dropdown filter for each columns. The options in the dropdown will be rendered with bootstrap 4 custom checkboxes.

8.2.1. Example (Single select)

...
columns: [
    {
        label: "First Name",
        name: "name.first_name", // access nested objects properties with "."
        filter: {
            type: "select",
            mode: "single",
            closeDropdownOnSelection: true,
            placeholder: "Select options",
            options: [{
                    "name": "option one",
                    "value": "option one"
                },
                {
                    "name": "option two",
                    "value": "option two"
                },
                {
                    "name": "option three",
                    "value": "option three"
                }
            ],
            init: {
                value : 2
            }
        }
    }
]
...

8.2.2. Example (Multi select)

...
columns: [
    {
        label: "First Name",
        name: "name.first_name", // access nested objects properties with "."
        filter: {
            type: "select",
            mode: "multi",
            closeDropdownOnSelection: true,
            placeholder: "Select options",
            options: [{
                    "name": "option one",
                    "value": "option one"
                },
                {
                    "name": "option two",
                    "value": "option two"
                },
                {
                    "name": "option three",
                    "value": "option three"
                }
            ],
            select_all_checkbox : {
                visibility: true,
                text: "Select all items"
            },
            init: {
                value : [0,1]
            }
        }
    }
]
...

8.2.3. Attribute details

9. Global search

Global search searches the complete list of rows for the given search keyword.

You can enable or disable search text input with custom configuration as shown in the below example.

9.1. Example

<template>
    <div id="app">
        
        
    </div>
</template>

9.2. Attributes details

9.3. Clear button icon slot

You can override the default clear button icon in the global search text input.

...

    <template slot="global-search-clear-icon">
        <i class="fas fa-times-circle"></i>
    </template>

...

10. Pagination & Info

Pagination component is built based on Bootstrap 4 pagination template. You can enable or disable pagination and pagination info details based on your choice.

Default pagination component

Default pagination info compoent

10.1. Example

<template>
    <div id="app">
        
        
    </div>
</template>

10.2. Attributes details

10.3. Slot

Currently you can override "Previous" & "Next" button icon/text.

10.3.1. Previous & Next button

...

    <template slot="paginataion-previous-button">
        Previous
    </template>
    <template slot="paginataion-next-button">
        Next
    </template>

...

After applying the above custom template to previous and next button, pagination component will look like this.

Pagination after applying slot

10.3.2. Pagination info

...

    <template slot="pagination-info">
        This page total is {{props.currentPageRowsLength}} |
        Filterd results total is {{props.filteredRowsLength}} |
        Original data total is {{props.originalRowsLength}}
    </template>

...

After applying the above custom template to pagination info , pagination info component will look like this.

Pagination info after applying slot

10.3.2.1. props

From slot-scope="props" you can access the following attributes.

10.3.3. Selected rows info

...

    <template slot="selected-rows-info">
        Total Number of rows selected : {{props.selectedItemsCount}}
    </template>

...

10.3.3.1. props

From slot-scope="props" you can access the following attributes.

11. Refresh and Reset button

11.1. Refresh Button

Refresh button emits a refresh event to your application (parent component). You can listen for this event and make ajax call for new data and update rows data. Table will receive the new data and update the rows with current queries.

11.1.1. Example

<template>
    <div id="app">
        
        
    </div>
</template>

11.2. Reset button

Reset button resets currently applied sorting, filtering, and global search queries.

By default reset button is enabled. If you would like to disable reset button, set show_reset_button to false in initial config.

11.3. Slots

11.3.1. Button text and icons

You can override the text in the refresh & reset buttons with slots refresh-button-text & reset-button-text. If you like, you can add icon to the buttons.

11.3.1.1. Example

...

    <template slot="refresh-button-text">
        <i class="fas fa-sync-alt"></i> My refresh
    </template>
    <template slot="reset-button-text">
        <i class="fas fa-broom"></i> My reset
    </template>

...

After applying the above custom template to refresh & reset buttons , output will look like this.

Custom refresh and reset button texts & icons

12. Custom action buttons

You can add your custom buttons in the table by actions props and listen for their events in your component.

12.1. Example

<template>
    <div id="app">
        
        
    </div>
</template>

Each action object should contain the below attributes.

12.2. Attributes details

13. Custom classes

You can pass your classes for the table, row, cell, etc.. via classes prop. And interesting thing is you can pass a validator function to apply custom classes conditionally.

13.1. Example

<template>
    <div id="app">
        
        
    </div>
</template>

Currently you can add custom classes to **`

    ...

        ...
    <table></table>
</div>

<template>
    <div id="app">
        
        
    </div>
</template>

<template>
    <div id="app">
        
        
    </div>
</template>



<style>

</style>

queryParams: {
    sort: [],
    filters: [],
    global_search: "",
    per_page: 10,
    page: 1,
},
total_rows: 0,

onChangeQuery(queryParams) {
    this.queryParams = queryParams;
    this.fetchData();
},

fetchData() {
    let self = this;
    axios.get('https://example.com/search', {
            params: {
                "queryParams": this.queryParams,
                "page": this.queryParams.page
            }
        })
        .then(function(response) {
            self.rows = response.data.data;
            self.total_rows = response.data.total;
        })
        .catch(function(error) {
            console.log(error);
        });
}

columns: [
    ...
    {
        label: "id",
        name: "id",
        filter: {
            type: "simple",
            placeholder: "Enter id"
        },
        sort: true,
        uniqueId: true // like this
    }
    ...
]

# install dependencies
npm install

# serve with hot reload at localhost:8080 (if it is not running in 8080, then check console for right port)
npm run dev

# build for production with minification
npm run build

# build for production and view the bundle analyzer report
npm run build --report

# run unit tests
npm run unit

# run all tests
npm test