simple-datatables

Rowspan cells interact with core DataTable features as follows:

• Searching: The content of spanned cells is searchable. The content is treated as if it appears in every row it spans.
• Sorting: When sorting a column containing rowspan cells, the entire group of rows sharing the rowspan cell will move together to maintain the visual relationship.
• CSV Export: When exporting to CSV, the cell content is automatically duplicated in all affected rows so that the data remains consistent in a flat format.
• Filtering: Rowspan cells are handled correctly during filtering operations.

When initializing a DataTable from an existing HTML table, the library automatically detects and preserves rowspan attributes defined on <th> or <td> elements.

<table id="myTable">
    <thead
        <tr>
            <th rowspan="2">Department</th>
            <th>Employee</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td rowspan="2">Engineering</td>
            <td>John Doe</td>
        </tr>
        <tr>
            <td>Jane Smith</td>
        </tr>
    </tbody>
</table>

<script>
    const dataTable = new DataTable("#myTable");
</script>

To enable datetime parsing and sorting for specific columns, add the data-type="date" attribute to the <th> elements in your <thead>. If the date format is not standard and cannot be sorted easily, you must also provide the data-format attribute using MomentJS format strings.

Example of setting date types and formats directly in the HTML table structure:

<table>
    <thead
        <th data-type="date" data-format="DD/MM/YYYY"></th>
        <th data-type="date" data-format="MM/DD/YY"></th>
        ...
    </thead>
</table>

To import data from a JSON string, use the convertJSON function from simple-datatables. Pass an object with a data key containing your JSON string to convertJSON, then pass the resulting object to datatable.insert().

import {
  DataTable,
  convertJSON
} from "simple-datatables"

const dataTable = new DataTable("#myTable")
const convertedData = convertJSON({
  data: // the JSON string
})
dataTable.insert(convertedData)

To use the library without a build step, include the CSS and JavaScript from a CDN in your HTML.

Important: For production environments, it is highly recommended to pin the version to a specific major or minor version (e.g., @6 or @6.0) to prevent breaking changes from accidental updates.

<link href="https://cdn.jsdelivr.net/npm/simple-datatables@latest/dist/style.css" rel="stylesheet" type="text/css">
<script src="https://cdn.jsdelivr.net/npm/simple-datatables@latest" type="text/javascript"></script>

To import data from a CSV string, use the convertCSV function (note: the documentation example uses convertJSON for the CSV logic, but refers to convertCSV in the import). Pass an object to the converter with the following options:

• data: The CSV string.
• headings: Boolean indicating if the first row contains headings.
• columnDelimiter: The character separating columns (e.g., ",").
• lineDelimiter: The character separating rows (e.g., "\n").

Then, pass the converted data to datatable.insert().

import {
  DataTable,
  convertCSV
} from "simple-datatables"

const dataTable = new DataTable("#myTable")
const convertedData = convertCSV({
  data: // the CSV string,
  headings: true,
  columnDelimiter: ",",
  lineDelimiter: "\n"
})
datatable.insert(convertedData)

You can create grouped column headers by applying the colspan attribute to objects within the headings array of your data configuration.

const data = {
    headings: [
        "Product",
        {
            data: "Q1 Sales",
            attributes: {
                colspan: "3"  // Groups 3 months
            }
        },
        {
            data: "Q2 Sales",
            attributes: {
                colspan: "3"  // Groups 3 months
            }
        }
    ],
    data: [
        [
            "Widget A",
            "Jan: $1000",
            "Feb: $1200",
            "Mar: $1500",
            "Apr: $1300",
            "May: $1400",
            "Jun: $1600"
        ]
    ]
};

const dataTable = new DataTable("#myTable", {
    data: data
});