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/.

Themes on this page:

1. Display — width, caption, initial order
2. Ajax & data — sources and request shaping
3. Features — info, paging, search, ordering toggles
4. Scrolling / pagination / search / i18n / layout — detailed knobs

Display

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:

Ajax 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 the DataTables paging layout feature (number of page buttons, first/last, previous/next, …). These keys are not the top-level boolean paging option: the bundle rewrites unmarked layout slots ('paging', { paging: true }, { paging: [] }) to { paging: { … } } when the table is serialized.

An explicit { paging: { buttons: 3 } } already placed in layout() is left as-is. withoutPaging() still disables pagination with paging: false.

$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); // British English

Styling

styleFramework

Declare which CSS framework the table renders against, instead of relying on the frontend to detect it from the page’s stylesheets:

use Pentiminax\UX\DataTables\Enum\StyleFramework;

$dataTable->styleFramework(StyleFramework::Bootstrap5);

Autodetection inspects document.styleSheets at connect time, looking for a recognized DataTables stylesheet href. Under a lazily-loaded Stimulus controller (fetch: "lazy"), the app’s own stylesheet import can still be in flight when detection runs, which can misdetect the framework or fall back to the plain dt styling. Setting styleFramework() skips detection entirely for that table, so there’s nothing to race. Tables that don’t set it keep using autodetection as before — this option is purely additive.

Available cases: DataTables (dt), Bootstrap (bs), Bootstrap4 (bs4), Bootstrap5 (bs5).

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,
]);

buttons

The Buttons extension needs both a button list and a Feature::BUTTONS marker in the layout. buttons() writes both at once, defaulting to the topStart position and keeping the features that position already holds. See the Buttons extension page.

use Pentiminax\UX\DataTables\Enum\ButtonType;

$dataTable->buttons([ButtonType::CSV, ButtonType::EXCEL], 'topEnd');

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)
    ->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'
    );