Load DataTables Data via Ajax (JSON shape)

To load data into DataTables via Ajax, pass an ajax URL and a columns array to $('#table').DataTable({ ... }). The server returns JSON with a top-level data array containing one object per row, and DataTables maps each columns[i].data key to that row’s matching property.

Contents

Client-side load (every row, paginate in the browser)
The JSON shape
PHP example for the endpoint
Bare array response — dataSrc: ''
Add a custom action column
For larger datasets — server-side processing
Frequently asked questions
Related guides
References

Last verified: 2026-05-17 with DataTables 2.0. Originally published 2022-11-06, rewritten and updated 2026-05-17.

Client-side load (every row, paginate in the browser)

$(document).ready(function () {
    $('#my-table').DataTable({
        ajax: '/api/employees',
        columns: [
            { data: 'name' },
            { data: 'position' },
            { data: 'office' },
            { data: 'extn' },
            { data: 'start_date' },
            { data: 'salary' },
        ],
    });
});

DataTables fetches the full dataset once and handles paginate/sort/search client-side. Fine for hundreds of rows; switch to server-side processing past that.

DataTables Ajax load — JSON shape, columns mapping, custom render, server-side flag

The JSON shape

{
  "data": [
    {
      "id": 1,
      "name": "Tiger Nixon",
      "position": "System Architect",
      "salary": "$320,800",
      "start_date": "2011/04/25",
      "office": "Edinburgh",
      "extn": "5421"
    },
    {
      "id": 2,
      "name": "Garrett Winters",
      "position": "Accountant",
      "salary": "$170,750",
      "start_date": "2011/07/25",
      "office": "Tokyo",
      "extn": "8422"
    }
  ]
}

PHP example for the endpoint

<?php
header('Content-Type: application/json');

$rows = [
    [
        'id' => 1, 'name' => 'Tiger Nixon', 'position' => 'System Architect',
        'salary' => '$320,800', 'start_date' => '2011/04/25',
        'office' => 'Edinburgh', 'extn' => '5421',
    ],
    [
        'id' => 2, 'name' => 'Garrett Winters', 'position' => 'Accountant',
        'salary' => '$170,750', 'start_date' => '2011/07/25',
        'office' => 'Tokyo', 'extn' => '8422',
    ],
];

echo json_encode(['data' => $rows]);

The whole response is wrapped in { "data": [...] } because DataTables reads rows from data by default.

Bare array response — `dataSrc: ''`

$('#my-table').DataTable({
    ajax: { url: '/api/employees', dataSrc: '' },
    columns: [ /* ... */ ],
});

// Endpoint now returns a bare array:
// [ { id: 1, name: ... }, { id: 2, ... } ]

Useful when you can’t change the server to wrap the array (third-party API, fixed-shape endpoint).

Add a custom action column

columns: [
    { data: 'name' },
    { data: 'position' },
    // ...
    {
        data: null,
        orderable: false,
        searchable: false,
        render: (data, type, row) =>
            `<a href="/employees/${row.id}/edit">Edit</a>`,
    },
],

data: null means “no source field” — the cell content comes from render, which receives the entire row. Mark such columns orderable: false and searchable: false so DataTables doesn’t try to sort or search on the HTML.

For larger datasets — server-side processing

$('#my-table').DataTable({
    serverSide: true,
    processing:  true,
    ajax:        '/api/employees',
    columns:     [ /* ... */ ],
});

With serverSide: true, every interaction sends a fresh request with pagination/sort/search params, and the server returns just the slice. See DataTables server-side pagination for the request/response contract.

Frequently asked questions

Why does my Ajax response need a data wrapper?

DataTables expects the row array under a key by default (the key is configurable via ajax.dataSrc; default is 'data'). The wrapper lets you include other top-level fields too — pagination metadata, server timestamps, debug flags — without DataTables choking on them. If you can’t change the server to wrap the array, set ajax: { url: '...', dataSrc: '' } to read a bare array.

What’s the difference between ajax and serverSide: true?

With just ajax, DataTables fetches every row once and paginates/sorts/searches them in the browser — fine for hundreds of rows. With serverSide: true, every interaction (page change, sort click, search keystroke) sends a fresh Ajax request and your server returns just the slice for that view. Use server-side when the dataset is too large to ship at once.

Why don’t my columns line up if my JSON has more fields than the table?

DataTables maps each columns[i].data entry to a property on the row object. Extra fields in JSON are ignored — they don’t appear because there’s no column for them. Fields missing from JSON show up as undefined in their column; add defaultContent: '' to suppress the warning.

How do I add a custom “Action” column with edit/delete buttons?

Use columns.render for one column: { data: null, render: (data, type, row) => `<a href="/edit/${row.id}">Edit</a>` }. data: null tells DataTables there’s no field to read; render generates the cell HTML from the whole row object.