Data tables

The v-data-table component is used for displaying tabular data. Features include sorting, searching, pagination, grouping, and row selection.

Usage

The standard data table presumes that the entire data set is available locally. Sorting, pagination, and filtering is supported and done internally by the component itself.

API

Component	Description
v-data-table	Primary Component
v-data-table-footer	Functional Component used to display Data-table headers
v-checkbox-btn	Reusable lightweight v-checkbox

Server side tables

This variant of the data table is meant to be used for very large datasets, where it would be inefficient to load all the data into the client. It supports sorting, filtering, pagination, and selection like a standard data table, but all the logic must be handled externally by your backend or database.

Find more information and examples on the Server side tables page.

Virtual tables

The virtual variant of the data table relies, like the standard variant, on all data being available locally. But unlike the standard variant it uses virtualization to only render a small portion of the rows. This makes it well suited for displaying large data sets. It supports client-side sorting and filtering, but not pagination.

Find more information and examples on the Virtual tables page.

Guide

The v-data-table component is a simple and powerful table manipulation component. It is perfect for showing large amounts of tabular data.

Items

Table items can be objects with almost any shape or number of properties. The only requirement is some form of unique identifier if row selection is being utilized.

Headers

The headers array is the core of the table. It defines which properties to display, their associated labels, how they should be sorted, and what they should look like.
All properties are optional, but at least one of title, value, or key should be present to display more than just an empty column:

headers = [
  { title: 'No data, just a label' },
  { key: 'quantity' },
  { value: 'price' },
]

Without any headers defined, the table will use all the keys of the first item as headers.

Headers can also be a tree structure with a children property to create multi-row header labels with rowspan and colspan calculated automatically.
Leaf nodes (objects without children) will be used as columns for each item.
Branch nodes (objects with children) support all the same sorting and filtering options as leaf nodes, but cannot be used as columns.

Keys and values

The key property is used to identify the column in slots, events, filters, and sort functions. It will default to the value property if value is a string.
value maps the column to a property in the items array. If value is not defined it will default to key, so key and value are interchangeable in most cases. The exception to this is reserved keys like data-table-select and data-table-expand which must be defined as key to work properly.
key and value both support dot notation to access properties of nested objects, and value can also be a function to combine multiple properties or do other custom formatting. If value is not a string then key must be defined.

items = [
  {
    id: 1,
    name: {
      first: 'John',
      last: 'Doe',
    },
  }
]
headers = [
  { title: 'First Name', value: 'name.first' },
  { title: 'Last Name', key: 'name.last' },
  {
    title: 'Full Name',
    key: 'fullName',
    value: item => `${item.name.first} ${item.name.last}`,
  },
]

Sorting, filtering, pagination

See Data and display.

Customization

Other options are available for setting width, align, fixed, or pass custom props to the header element with headerProps and row cells with cellProps.

Props

There are no shortable of properties available for customizing various aspects of the Data table components.

Density

Using the density prop you are able to give your data tables an alternate style.

Hide default header and footer

You can apply the hide-default-header and hide-default-footer props to remove the default header and footer respectively.

Selection

The show-select prop will render a checkbox in the default header to toggle all rows, and a checkbox for each row.

For more information and examples, see the selection examples page.

Simple checkbox

When wanting to use a checkbox component inside of a slot template in your data tables, use the v-checkbox-btn component rather than the v-checkbox component. The v-checkbox-btn component is used internally and will respect header alignment.

Slots

Header slot

You can use the dynamic slots header.<key> to customize only certain columns. <key> corresponds to the key property in the items found in the headers prop.

INFO

There are two built-in slots for customizing both the select (header.data-table-select) and expand (header.data-table-expand) columns when using show-select and show-expand props respectively.

Headers slot

You can also override all the internal headers by using the headers slot. Remember that you will have to re-implement any internal functionality like sorting.

Item slot

Normally you would use the item.<key> slots to render custom markup in specific columns. If you instead need more control over the entire row, you can use the item slot.

Item key slot

You can use the dynamic slots item.<key> to customize only certain columns. <key> is the name of the key property in header items sent to headers. So to customize the calories column we're using the item.calories slot.

Group header slot

When using the group-by prop, you can customize the group header with the group-header slot.

Loading slot

The loading slot allows you to customize your table's display state when fetching data. In this example we utilize the v-skeleton-loader component to display a loading animation.

Examples

The following are a collection of examples that demonstrate more advanced and real world use of the v-data-table component.

CRUD Actions

v-data-table with CRUD actions using a v-dialog component for editing each row

Expandable rows

The show-expand prop will render an expand icon on each row. You can customize this with the item.data-table-expand slot. The position of this slot can be changed by adding a column with key: 'data-table-expand' to the headers array.

Just like selection, row items require a unique property on each item for expansion to work. The default is id, but you can use the item-value prop to specify a different item property.