Vue

Vue.js is a front-end Javascript framework that is widely used for creating reactive web-applications. We publish the datatables.net-vue3 package which provides DataTables for use as a component in Vue3 applications.

Installation and importing

Install the datatables.net-vue3 and datatables.net-dt packages using your package manager:

# npm
npm install --save datatables.net-vue3 datatables.net-dt

# yarn
yarn add datatables.net-vue3 datatables.net-dt

To then use DataTables component in your own components, you need to import both it and DataTables core, then assign DataTables core as the library to use in the component like this:

import DataTable from 'datatables.net-vue3';
import DataTablesCore from 'datatables.net-dt';

DataTable.use(DataTablesCore);

This will give you a <DataTable> Vue component you can use in your templates.

Styling

It might seem like an unnecessary extra step to import the datatables.net-dt package - why don't we just have a dependency on that package? DataTables supports a number of different styling frameworks (Bootstrap, Bulma, Foundation, etc), each of which is published as a different package, so what we are doing here is importing the DataTables default styling package and then assigning that as the library to be used by the Vue component.

If you wanted to make use of DataTables' Bootstrap 5 integration you could install the datatables.net-bs5 package and use that:

import DataTable from 'datatables.net-vue3';
import DataTablesCore from 'datatables.net-bs5';

DataTable.use(DataTablesCore);

Note the key use of the postfix -bs5 rather than -dt in the package name to change the styling integration.

Use the download builder to make sure you get the packages you need (and only those packages!).

Extensions

You can also install DataTables extensions from their own npm packages and use them in the standard manner - e.g. for both Select and Responsive you might use:

# npm
npm install --save \
    datatables.net-select-dt \
    datatables.net-responsive-dt

# yarn
yarn add \
    datatables.net-select-dt \
    datatables.net-responsive-dt

Note the use of the -dt postfix for the styling again - this will change based on the styling package you need - again, use the download builder to get the package names you need!

For each extension, you need to import it for it to be registered with DataTables. For example, to use both Select and Responsive:

import DataTable from 'datatables.net-vue3';
import DataTablesCore from 'datatables.net-dt';
import 'datatables.net-select-dt';
import 'datatables.net-responsive-dt';

DataTable.use(DataTablesCore);

Note that you will also need to provide initialisation options for the extensions (e.g. select and responsive in this case). Please see the Use section below for details on passing configuration options.

The same installation applies to all of the other DataTables extensions. Use the download builder to get a list of the npm packages for the extensions you want.

Use

Once installed and registered in your component you will have a <DataTable> tag available for use in your Vue template (you can change the name by changing the import statement used above if you prefer something else). It has a single optional slot which can be used to describe the table with headers and footers:

<DataTable class="display">
    <thead>
        <tr>
            <th>First</th>
            <th>Second</th>
        </tr>
    </thead>
</DataTable>

The <DataTable> component has the following parameters available:

• columns - Define the columns array used for DataTables initialisation
• data - Data array for DataTables. This is optional and if you are using Ajax to load the DataTable data is not required.
• ajax - Ajax option for DataTables - to load data for the table over Ajax.
• class - Class name to assign to the table tag
• options - The DataTables options for the table. Note that this can include columns, data and ajax - if they are provided by one of the properties from above that will override a matching option given here.

Basic initialisation

The most basic example use of DataTables in a Vue application (Composition API) is:

<script setup>
import DataTable from 'datatables.net-vue3';
import DataTablesCore from 'datatables.net';

DataTable.use(DataTablesCore);

const data = [
  [1, 2],
  [3, 4],
];
</script>

<template>
    <DataTable :data="data" class="display">
        <thead>
            <tr>
                <th>A</th>
                <th>B</th>
            </tr>
        </thead>
    </DataTable>
</template>

Example: Basic initialisation.

Ajax data

You might wish to load data for the table to display via Ajax rather than using local Vue data. That can be done with the ajax parameter directed at the URL to load the data from:

<script setup lang="ts">
import DataTable from 'datatables.net-vue3';
import DataTablesCore from 'datatables.net';

DataTable.use(DataTablesCore);

const columns = [
  { data: 'name', title: 'Name' },
  { data: 'position', title: 'Position' },
  { data: 'office', title: 'Office' },
  { data: 'extn', title: 'Extension' },
  { data: 'start_date', title: 'Start date' },
  { data: 'salary', title: 'Salary' },
];
</script>

<template>
    <DataTable
        :columns="columns"
        ajax="/data.json"
        class="display"
    />
</template>

The boiler plate code is removed in the above for brevity.

Example: Ajax data example demonstrating how to use objects as the data source to populate the table via the columns.data option.

Events

DataTables emits a large number of events which can be useful to listen for and react to when the events happen. With the DataTables / Vue component, you can listen for the events just as you would with regular Vue event handlers - i.e. use a @ listener:

<DataTable
    ajax="/data.json"
    @xhr="xhrEvent"
    @draw="drawEvent"
>

This will listen for xhr and draw, calling the functions as given. The events will be given the same arguments as described in the DataTables documentation, with the exception of the first parameter passed in which is an object that contains:

{
    e: Event,
    dt: DataTables.Api
}

Example: Listening for events.

Extensions

The installation section above showed how to install and register a DataTables extension. Once they have been installed, they can be used in the standard DataTables way, through their initialisation options. In this example we initialise the Select and Responsive extension using the select option:

<script setup lang="ts">
import DataTable from 'datatables.net-vue3';
import DataTablesCore from 'datatables.net';
import 'datatables.net-responsive';
import 'datatables.net-select';

DataTable.use(DataTablesCore);

const columns = [
  { data: 'name', title: 'Name' },
  { data: 'position', title: 'Position' },
  { data: 'office', title: 'Office' },
  { data: 'extn', title: 'Extension' },
  { data: 'start_date', title: 'Start date' },
  { data: 'salary', title: 'Salary' },
];

const options = {
  responsive: true,
  select: true,
};
</script>

<template>
    <DataTable
        :columns="columns"
        :options="options"
        ajax="/data.json"
        class="display nowrap"
    />
</template>

Example: Responsive and Select extensions.

Example: Buttons extension for file export which requires the use of two additional functions to assign JSZip and pdfmake.

API

When working with DataTables, you will often want to use its API to unlock its full potential. This is possible through the dt() method that the datatables.net-vue3 component provides.

let dt;
const table = ref(); // This variable is used in the `ref` attribute for the component

onMounted(function () {
  dt = table.value.dt;
});

Note, make sure you add ref="table" to the <DataTable> component tag to get the reference to link up. Now you can make use of the API methods.

Reactive data

One of the most exciting and useful parts of Vue is Reactive data. In summary this is where you update data (e.g. variable = 1) the UI will automatically update to reflect this change - however complex that change might be. The datatables.net-vue3 package fully supports Vue's reactive data and will automatically reflect the changes made to the data.

Example: Reactive data

This example demonstrates the use of the DataTables API to dynamically update the table in responsive to Vue's reactive data. Note how we don't need to tell DataTables about the new data through any API method calls - it just updates automatically.

Vue Components

You will likely wish to show Vue components inside a DataTable's cells. To do this, the DataTable component supports the use of named slots, with both automatic and manual assignment based on the name of the slot.

Automatic slots

The DataTables Vue component will automatically look for slots with the following name patterns and assign them to the matching column:

• column-{integer} - Assign this slot to the column of a matching index (zero based)
• column-{string} - Assign this slot to a column which has its columns.name property set to the {string}.

Consider the following DataTable component with two named slots:

<template>
    <DataTable ajax="/data.json">
        <template #column-1="props">
            <Button
                :text="`Col 1: ${props.cellData}`"
                @click="rowClick(props.rowData)"
            ></Button>
        </template>
        <template #column-extn="props">
            <Button
                :text="`Extn: ${props.cellData}`"
                @click="rowClick(props.rowData)"
            ></Button>
        </template>
    </DataTable>
</template>

The first slot has the name column-1, so it is assigned to the second column in the table and the <Button> component will be displayed in the cell for each row. Note that the component makes use of the property passed into it - please see the Slot properties section below for more details. Also note that it is a regular Vue component and can have events, etc attached to it.

The second slot has the name column-extn and thus will be assigned to any column which has its name set to extn through the columns.name property.

Manual slots

There might be circumstances whereby you wish to set a custom name for the slot. For this, you can use the columns.render option set to a string matching your slot name with a # prefix. For example:

const columns = [
  // ...
  {
    data: null,
    render: '#action',
    title: 'Action'
  },
  // ...
];

This would be used with a slot called action like this:

<template>
    <DataTable ajax="/data.json">
        <template #action="props">
            <Button
                :text="`Col 1: ${props.cellData}`"
                @click="rowClick(props.rowData)"
            ></Button>
        </template>
    </DataTable>
</template>

The reason you might wish to use a custom name, rather than automatic detection is for orthogonal data. Orthogonal data allows DataTables to use different values for ordering, search and display data types, which is particularly important when a complex component is used.

As with DataTables' standard orthogonal data you can use the columns.render option as an object with a list of the data types and their value specifying where the value should be read from. To have the component displayed, use the display property set to the name of the slot to use (with a leading #).

const columns = [
  // ...
  {
    data: null,
    render: {
      _: 'name',
      display: '#action'
    },
    title: 'Action'
  },
  // ...
];

Please note that if you are not using orthogonal data, DataTables will use the contents of the component for actions such as ordering and search, as it would do with plain HTML.

Slot properties

Vue slots can be passed properties and we take advantage of that in the DataTables Vue component so you have access to the data for the cell to be rendered. You will likely have noticed the props attribute value that is used for the slot name in the examples above. This is an object made up of the following structure:

interface DataTablesNamedSlotProps {
    /** The data to show in the cell (from the `columns.data` configuration) */
    cellData: string;

    /** The column index for the cell (0-based index) */
    colIndex: Number;

    /** The data object for the whole row */
    rowData: any;

    /** Row index for the cell (data index, not the display index) */
    rowIndex: Number;

    /** Orthogonal data type */
    type: string;
}

These properties can be used to render the information needed for your component. Typically you will refer to cellData, but it can be useful to have access to the whole row's data object for more complex components which require multiple data points. The format of rowData will depend on how you populate the DataTable - it is the original data object that was given to DataTables (or an array if data is read from HTML).

Styling

DataTables' support for various styling libraries is fully supported in the Vue component. As an example, consider that we are using Bootstrap 5 - the rest of our page is Bootstrap 5 style based and our DataTable should reflect that. We have npm packages for DataTables core and all of its extensions that work with Bootstrap 5 (and other styling frameworks) - they end in -bs5 (e.g. datatables.net-bs5 for Bootstrap 5 and DataTables core), while the default styling has a -dt postfix. See the download builder to get the styling packages needs for your preferred framework.

With the default styling simply install the styling package:

# npm
npm install --save datatables.net-dt

# yarn
yarn add datatables.net-dt

And then include it in your <style> tag (note that we are using Vite to build the package here, which will resolve CSS styles from node packages as well as Javascript, allowing this to work):

<style>
@import 'datatables.net-dt';
</style>

For the other styling frameworks, you need to also include a Javascript element, which configures DataTables and its extensions to use the styles and DOM structure suitable for the framework selected - e.g. for Bootstrap 5:

# npm
npm install --save datatables.net-bs5

# yarn
yarn add datatables.net-bs5

And in your Vue component register the style in exactly the same way as you do with the extensions:

<script setup lang="ts">
import DataTable from 'datatables.net-vue3';
import DataTablesCore from 'datatables.net-bs5';

DataTable.use(DataTablesCore);

const columns = [
  { data: 'name' },
  { data: 'position' },
  { data: 'office' },
  { data: 'extn' },
  { data: 'start_date' },
  { data: 'salary' },
];
</script>

<style>
@import 'bootstrap';
@import 'datatables.net-bs5';
</style>

Example: You can see Vue + DataTables + Bootstrap 5 in action here.