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:

Client-side Processing And Data Sources

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.

urlState

Synchronise table state (search, ordering, page, page length) with the URL query string. Makes the URL shareable and restores state on page reload or browser back/forward navigation.

$dataTable->urlState();

Example URL produced:

?search=foo&order[name]=email&order[dir]=asc&start=20&pageLength=25

Disabling individual keys

Each key can be enabled or disabled independently:

$dataTable->urlState(['page' => false]);
// Search, ordering and pageLength reflected in URL; pagination ignored.

$dataTable->urlState(['search' => true, 'order' => false, 'page' => false, 'pageLength' => false]);
// Only search is synchronised.

Supported keys: search, order, page, pageLength (all true by default).

Prefix for multiple tables on the same page

To avoid query-string collisions when multiple DataTables share the same page, pass a prefix:

$usersTable->urlState(prefix: 'users');
$ordersTable->urlState(prefix: 'orders');

Resulting URL:

?users[search]=alice&users[order][name]=id&users[order][dir]=asc&orders[start]=10&orders[pageLength]=25

Bracket notation is written unencoded (human-readable) and is natively parsed by PHP, Symfony, Laravel and Rails.

Multi-column ordering

When multiple columns are sorted, the format becomes indexed:

?order[0][name]=id&order[0][dir]=asc&order[1][name]=email&order[1][dir]=desc

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 using an array. Each position accepts a Feature enum, an array of features, null to hide, or a DataTables feature object.

use Pentiminax\UX\DataTables\Enum\Feature;

// Simple layout
$dataTable->layout([
    'topStart'    => Feature::PAGE_LENGTH,
    'topEnd'      => Feature::SEARCH,
    'bottomStart' => Feature::INFO,
    'bottomEnd'   => Feature::PAGING,
]);

// Multiple features per position
$dataTable->layout([
    'topEnd' => [Feature::SEARCH, Feature::BUTTONS],
]);

// Full-width row with custom HTML, null to hide a position
$dataTable->layout([
    'top'         => ['div' => ['html' => '<h2>My Table</h2>']],
    'topStart'    => Feature::PAGE_LENGTH,
    'bottomStart' => null,
    '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()
    ->caption('Product Catalog')
    ->language(Language::EN_GB)
    ->ordering(handler: true, indicators: true)
    ->paging(buttons: 5, firstLast: true)
    ->searching()
    ->serverSide()
    ->processing()
    ->scrollY('400px')
    ->pageLength(25)
    ->lengthMenu([10, 25, 50, 100])
    ->stateSave()
    ->urlState()
    ->layout([
        'topStart'    => Feature::PAGE_LENGTH,
        'topEnd'      => Feature::SEARCH,
        'bottomStart' => Feature::INFO,
        'bottomEnd'   => Feature::PAGING,
    ])
    ->ajax(
        url: '/api/products',
        dataSrc: 'data',
        type: 'GET'
    );