Usage guide

In the quick start guide you saw how to get DataTables installed and displaying data in your Vue app. Let's take that to the next level now and go into a bit more detail so you can see how to customise the table to your needs.

Table configuration

First up, let's consider how you can configure the DataTable to suit your needs. DataTables has a wide range of options - for example, the ability to set the default page length, control where table control elements are shown and language options. These can be set using the options parameter for the <DataTable> component:

<script setup lang="ts">
    import DataTable, { Column } from 'datatables.net-vue3';
    import DtCore, { Options } from 'datatables.net-bs5';

    // Assign DataTables core
    DataTable.use(DtCore);

    // DataTables options
    const options: Options = {
        pageLength: 25,
        scrollY: true
    };
</script>

<template>
    <DataTable ajax="/api/data" :options="options">
        <Column ... />
    </DataTable>
</template>

Here we use pageLength to set the default page length and scrollY to enable DataTables' scrolling mode. All of the configuration options for DataTables can be defined through this object allowing extensive customisation of the table display.

Ajax data

You might also have spotted that ajax is used in the above, rather than the data property. This property maps to DataTables' ajax option and instructs it to get the data to display in the table from a remote Ajax source. Depending on how your app works, you might find this to be a useful way of populating the table.

For more details on using DataTables options with the Vue component, please see the <DataTable> documentation.

Column options

We've already see above how the <Column> component can have properties defined - e.g. title and data. The most commonly used column options are available as properties, but there are a wide range of options available, such as setting the default visibility, if a column should be orderable, and more. These options can be provided through the options property for <Column> - e.g.:

<template>
    <DataTable :data="rows">
        <Column title="ID" data="id" :options="{orderable: false, searchable: false}" />
    </DataTable>
</template>

Components

Inevitably you will want to use Vue components in your table cells - adding event handlers, routes and so on. This is done by giving the component as a child of <Column>. For example to create a button that has the row id:

<template>
    <DataTable :data="rows">
        <Column title="ID" data="id" v-slot="props">
            <Button :id="props.cellData" />}
        </Column>
    </DataTable>
</template>

This is implemented through Vue's slots, where the child of <Column> is the default slot (<Column> doesn't provide any named slots, just the default). The properties of each cell are available through the v-slot attribute, which include cellData and rowData.

For the full interface and property details, please see the <Column> documentation.

Styling

You might have noticed the use of the -dt postfix for the DataTables core package above. DataTables supports multiple different styling frameworks such as Bootstrap, Bulma and Fomantic UI, each with its own package. The -dt denotes the default styling for DataTable.

Use the DataTables download builder to get a list of the packages to for the styling integration you want.

To include the relevant CSS in your component, include the styling package to your <style> tag - e.g. for the Bootstrap 5 styling integration use:

<style>
    @import url('datatables.net-bs5');
</style>

The style include can also be performed at a higher level in your app (an application level stylesheet for example), so you need only include it once. Please note that the styling packages cannot be scoped as they wouldn't apply to the target table.

Extensions

DataTables has a wide range of extensions which extend the capabilities of DataTables. This includes abilities such as advanced editing through Editor, Excel like navigation though KeyTable and AutoFill.

Let's take a look at the installation of two extensions - Buttons and CardView. This will show the basic principle of how to install DataTables extensions - the others all follow the same basic pattern, each with their own specific configuration options in the table initialisation object.

Buttons

The Buttons extension for DataTables provides a common framework to describe table control buttons. You can create custom buttons and also make use of the default buttons that Buttons ships with, including the ability to export the table's data to CSV, Excel and PDF.

To install Buttons use the download builder and select the Buttons package (along with any others). Here I'll assume you are using the default styling so the datatables.net-buttons-dt package is required.

<script setup lang="ts">
    import jszip from 'jszip';
    import pdfmake from 'pdfmake';
    import DataTable, { Column } from 'datatables.net-vue3';
    import DtCore, { Options } from 'datatables.net-dt';
    import 'datatables.net-buttons-dt';

    // Assign libraries
    DataTable.use(DtCore);
    DtCore.use(jszip, 'jszip');
    DtCore.use(pdfmake, 'pdfmake');

    const options: Options = {
        layout: {
            topStart: 'buttons'
        }
    };
</script>

<style>
    @import url('datatables.net-dt');
    @import url('datatables.net-buttons-dt');
</style>

<template>
    <DataTable ajax="/api/data" :options="options">
        <Column ... />
    </DataTable>
</template>

Note that in this case we've included the JSZip and pdfmake libraries as well. These are used to provide the export file formats and need to be registered with DataTables' DataTable.use() method so they can be "seen" by the Buttons library.

To display the Buttons, we use the layout option and define where we want the default buttons to display (topStart in this case). The options object is then used to configure the DataTable.

For more information on the Buttons library, including controlling what buttons are shown and adding custom buttons, please see the Buttons manual.

Example: Vue DataTables with export buttons

CardView

DataTables features a number of "Plus" extensions, which are available as part of DataTables Plus - a suite of commercial extensions that extend the capabilities of the core library. One of these extensions is CardView, which will display the table rows as "cards" when the display is sufficiently narrow - ideal for mobile, tablets or even complex data grids on larger monitors such as shopping carts. You still get all the benefits of DataTables' advanced search, etc.

To install CardView, use the download builder and select the CardView extension and install as normal:

npm install datatables.net-cardview-dt

Then include the software in your app:

<script setup lang="ts">
    import DataTable, { Column } from 'datatables.net-vue3';
    import DtCore from 'datatables.net-dt';
    import 'datatables.net-cardview-dt';

    // Assign libraries
    DataTable.use(DtCore);

    const options = {
        cardView: true
    };
</script>

<style>
    @import url('datatables.net-dt');
    @import url('datatables.net-cardview-dt');
</style>

<template>
    <DataTable ajax="/api/data" :options="options">
        <Column ... />
    </DataTable>
</template>

Note that here, the options object includes the cardView option in the options property to enable this feature.

By default, CardView will activate automatically when the output is narrow, and then switch back to table view when the display is wide enough. This behaviour can be controlled and even buttons added to allow the end user to select which mode they wish to use.

Example: Vue DataTables with CardView

Next steps

The Vue component for DataTables unlocks the flexibility of DataTables with the power of Vue. This document has given you an overview of how to use the two together effectively, but there is of course still more to learn. The DataTables core documentation details the capabilities of DataTables, while the rest of the Vue DataTables documentation delves into how to use the components introduced here in more detail.