Options

This page documents the PHP helper methods available on the DataTable class to configure DataTables options. For a complete API inventory, see /ux-datatables/reference/datatable/.

Basic Configuration

autoWidth

Controls DataTables’ smart column width calculation:

$dataTable->autoWidth(true);  // Enable (default)
$dataTable->autoWidth(false); // Disable for custom widths

caption

Sets a caption for the table:

$dataTable->caption('Monthly Sales Summary');

order

Sets the initial column ordering:

$dataTable->order([
    [0, 'asc'],        // First column ascending
    [2, 'desc'],       // Third column descending
]);

Order format options:

Data Loading

ajax

Load data from an HTTP endpoint:

$dataTable->ajax('/api/data');

// With full configuration
$dataTable->ajax(
    url: '/api/data',
    dataSrc: 'data',      // JSON key containing rows
    type: 'POST'          // HTTP method
);

data

Set data directly:

$dataTable->data([
    ['id' => 1, 'name' => 'Product A'],
    ['id' => 2, 'name' => 'Product B'],
]);

Feature Control

deferRender

Defer rendering of rows not immediately visible:

$dataTable->deferRender(true);  // Improves initial load time

info

Toggle the information summary (“Showing 1 to 10 of 50 entries”):

$dataTable->info(true);   // Show (default)
$dataTable->info(false);  // Hide

lengthChange

Allow users to change page length:

$dataTable->lengthChange(true);   // Show selector (default)
$dataTable->lengthChange(false);  // Hide selector

ordering / withoutOrdering

Control sorting behavior:

// Enable with options
$dataTable->ordering(handler: true, indicators: true);

// Disable completely
$dataTable->withoutOrdering();

paging / withoutPaging

Configure pagination:

$dataTable->paging(
    boundaryNumbers: true,   // Show first/last page numbers
    buttons: 7,              // Number of page buttons
    firstLast: true,         // Show First/Last buttons
    numbers: true,           // Show page numbers
    previousNext: true,      // Show Previous/Next buttons
);

// Disable pagination
$dataTable->withoutPaging();

processing

Show a processing indicator during Ajax requests:

$dataTable->processing(true);

searching

Enable/disable the search box:

$dataTable->searching(true);   // Enable (default)
$dataTable->searching(false);  // Disable

serverSide

Enable server-side processing:

$dataTable->serverSide(true);

stateSave

Restore table state after page reload:

$dataTable->stateSave(true);

Saves: page position, ordering, search term, page length.

Scrolling

scrollX

Enable horizontal scrolling:

$dataTable->scrollX(true);

scrollY

Enable vertical scrolling with fixed height:

$dataTable->scrollY('400px');
$dataTable->scrollY('50vh');

Pagination Options

displayStart

Set the starting row for display:

$dataTable->displayStart(20);  // Start at row 21

lengthMenu

Configure page length options:

$dataTable->lengthMenu([10, 25, 50, 100]);

// With custom labels
$dataTable->lengthMenu([
    [10, 25, 50, -1],
    ['10 rows', '25 rows', '50 rows', 'All']
]);

pageLength

Set initial page length:

$dataTable->pageLength(25);

Search Options

search

Set initial search value:

$dataTable->search('active');

withSearchOption

Full search configuration:

use Pentiminax\UX\DataTables\Model\Options\SearchOption;

$dataTable->withSearchOption(SearchOption::new(
    caseInsensitive: true,
    regex: false,
    return: false,
    search: 'priority',
    smart: true,
    searchDelay: 300,  // Debounce in ms
));

Internationalization

language

Set the UI language:

use Pentiminax\UX\DataTables\Enum\Language;

$dataTable->language(Language::FR);    // French
$dataTable->language(Language::DE);    // German
$dataTable->language(Language::ES);    // Spanish
$dataTable->language(Language::EN_GB); // British English

Layout

layout

Position UI components:

use Pentiminax\UX\DataTables\Enum\Feature;

$dataTable->layout(
    topStart: Feature::PAGE_LENGTH,
    topEnd: Feature::SEARCH,
    bottomStart: Feature::INFO,
    bottomEnd: Feature::PAGING,
);

Complete Example

use Pentiminax\UX\DataTables\Enum\Feature;
use Pentiminax\UX\DataTables\Enum\Language;
use Pentiminax\UX\DataTables\Model\DataTable;

$dataTable = new DataTable('products');

$dataTable
    ->autoWidth(true)
    ->caption('Product Catalog')
    ->language(Language::EN_GB)
    ->ordering(handler: true, indicators: true)
    ->paging(buttons: 5, firstLast: true)
    ->searching(true)
    ->serverSide(true)
    ->processing(true)
    ->scrollY('400px')
    ->pageLength(25)
    ->lengthMenu([10, 25, 50, 100])
    ->stateSave(true)
    ->layout(
        topStart: Feature::PAGE_LENGTH,
        topEnd: Feature::SEARCH,
        bottomStart: Feature::INFO,
        bottomEnd: Feature::PAGING,
    )
    ->ajax(
        url: '/api/products',
        dataSrc: 'data',
        type: 'GET'
    );