Columns

When working with tables, you are going to need some columns! The easiest way to define them in the Vue component for DataTables is with the <Column> component that the package exports. When installing the package you might have noticed that there is a named Column property you can import along with the main <DataTable> component:

import DataTable, { Column } from 'datatables.net-vue3';

The <Column> component can be a child of the host <DataTable> (i.e. in the default slot) and defines how the column should be displayed.

When using <Column> you will typically specify a title and data property, which tells DataTables what the title text for the column should be, and where to get the data to display in the column for each row. These map to the columns.title and columns.data initialisations options for DataTables.

Consider this simple example:

<template>
    <DataTable ajax="/data.json">
        <Column title="Name" data="name" />
        <Column title="Position" data="position" />
        <Column title="Office" data="office" />
        <Column title="Extn." data="extn" />
        <Column title="Start date" data="start_date" />
        <Column title="Salary" data="salary" />
    </DataTable>
</template>

Here the table is instructed to show six columns, based on the data loaded from data.json.

Example: You can see this example here.

Properties

The <Column> component makes the following properties available:

• data - The data point that should be used for reading the data to display in the column from the row's data source. Maps to columns.data.
• footer - The text to show in the table footer for the column. Maps to columns.footer.
• options - Object of options for the columns. Can take any of the properties or values from the DataTables column configuration object.
• render - Define the rendering function used to display the data. Note that this cannot be used at the same time as a child component (see below).
• title - The text to show in the table header for the column. Maps to columns.title.

The data, footer and title options are provided as properties for the component as a convenience, but they could equally be defined as part of the options object if you prefer. If both are defined, the property value will be used.

The <Column> properties are fully typed (if you are using TypeScript of course). The interface is:

interface ColumnProps {
    /** Column data source property */
    data?: ColumnData;

    /** Footer display title */
    footer?: string;

    /** Additional DataTables column options */
    options?: ColumnOptions;

    /** Custom renderer function or string formatter */
    render?: ColumnRender;

    /** Header display title */
    title?: string;
}

Column options

The options object offers a wealth of options to be able to control a column. For example columns.searchable controls if a column's contents will be included in the search data set for the column while columns.orderable define if a column can be ordered by the end user.

If we consider those two options and want to disable them for a specific column, you might use:

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

Child components

You will likely wish to show Vue components inside a DataTable's cells at some point. To do this the <Column> component can have children defined in the default slot that define what should be shown.

For example, if you wish to have a <Button> component in each cell, with data based on the value pointed to by the data property, use:

<Column title="Buttons" data="id" v-slot="props">
    <Button :text="props.cellData" />
</Column>

There are a number of important points to make here - the v-slot attribute is used to pass in information about the cell to be created. The interface for the properties are

interface ColumnSlotProps {
    /** 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;
}

Secondly, the default slot can take any valid Vue markup - for example, you can display text information directly, without a component:

<Column title="Telephone" data="tel" v-slot="{cellData}">
    <a :href="`tel:${cellData}`">{{cellData}}</a>
</Column>

In this case, v-slot="{cellData}" as been used to provide access to the cell data (this is an object destructor).

Example: Vue DataTables with child components

Top level columns option

You might have noticed in the <DataTable> documentation that it provides a columns property. This maps to the columns array that can be defined as part of the DataTables initialisation. As such, if you prefer, you can define columns using that array. The initialisation that matches the first example above is:

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

DataTable.use(DtCore);

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

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

Note that here there is no need to use the <Column> component in this case as the columns are fully defined by the columns property. Typically you would use one or the other, not both (although if both are defined, they will be merged).