DataTables logo
≡

DataTable

Once you have installed and registered DataTables you will have a <DataTable> component available for use in your component's template - i.e.:

<template>
    <DataTable />
</template>

On it's own, this is just an empty table and not very interesting! Next, we need to configure it with that columns we want to show, the data to be displayed and any configuration options to customise the table.

Child components / default slot

The <DataTable> component can be configured with a number of different types of children in the default slot (i.e. a child of <DataTable>):

  • <Column> components, exported by the DataTables Vue component. These can be used to define the columns to display and the data to display in each. Please see the <Column> component documentation for full details on its options and how to make use of it to display Vue elements.
  • <thead> - a regular HTML table header
  • <tfoot> - a regular HTML table footer
  • <tbody> - table body, with data if needed for a static table.

The header and footer can be automatically generated from the <Column> components, and typically you won't need to use thead or tfoot, however, they can be useful if you wish to create "complex" headers and footers for your table which involve colspan and rowspan attributes - e.g.:

<template>
    <DataTable>
        <thead>
            <tr>
                <th rowspan="2">Name</th>
                <th colspan="2">Position</th>
                <th colspan="3">Contact</th>
            </tr>
            <tr>
                <th colspan="3">HR info</th>
                <th colspan="2">Direct</th>
            </tr>
        </thead>
    </DataTable>
</template>

Important: Do not use v-for to populate the table with data unless the data is static (i.e. not reactive). Doing so would cause both DataTables and Vue to try and control the same DOM elements, resulting in unpredictable behaviour. Bind data using the data parameter, or use ajax to load remote data, and allow DataTables to populate the data for you!

Properties

To configure the DataTable, the component has the following properties that can be assigned for configuration:

  • ajax - Ajax option for DataTables - to load data for the table over Ajax.
  • className - Class name to assign to the table
  • columns - Define the columns array used for DataTables initialisation - note you are unlikely to need this if you use the <Column> component!
  • data - Data array for DataTables. This is optional and if you are using Ajax to load the DataTable this attribute should not be used.
  • 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.
  • @{event} - Event functions - see the Events section below.

Configuration options

The default DataTables configuration is simple and yet powerful, but you will likely wish to customise the UI that it presents on your page - for example to change the location of the search input bar, or to enable and configure extensions such as Buttons.

This is done through the options parameter which can take any of the DataTables configuration options:

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

DataTable.use(DtCore);

const options = {
    layout: [
        top: 'search',
        topStart: null,
        topEnd: null
    ],
    pageLength: 25
};
</script>

<template>
    <DataTable
        :options="options"
    >
        ...
    </DataTable>
</template>

In this case layout is used to remove the default search and page length controls, replacing them with a search input at the top of the table. The page length is also set to 25.

API

When working with DataTables, you will often want to use its API to unlock its full potential. This is possible through the ref attribute for the datatables.net-vue3 component.

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

DataTable.use(DtCore);

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

onMounted(function () {
  dt = table.value.dt;
});
</script>

<template>
    <DataTable
        ref="table"
        ajax="/data.json"
    >
        ...
    </DataTable>
</template>

Example: API access and usage.

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 using an @{name} property (where the name matches the event name you want to listen to):

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

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.

Example: Listening for events.

Named slots (legacy)

Prior to the introduction of the <Column> component in v4 of the datatables.net-vue3 package, components in columns were provided by named slots, as documented here. The following documentation is provided for backwards compatibility information.

This approach is now deprecated (although is not scheduled for removal) and should not be used for new projects. Use the <Column> component!

The Vue 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).