Styling

The bundle supports 4 DataTables CSS frameworks out of the box. The Stimulus controller automatically detects which stylesheet you have loaded and picks the matching JavaScript integration — no PHP configuration required.

How It Works

On page load, the controller scans the loaded stylesheets and matches the CSS file’s URL against known patterns. The first match wins, so more specific patterns (e.g. bootstrap5) are checked before less specific ones (e.g. bootstrap). If nothing matches, the bundle falls back to the DataTables default theme.

Switching Frameworks

With AssetMapper

Edit assets/controllers.json to enable the CSS file for your target framework and disable the others:

{
  "controllers": {
    "@pentiminax/ux-datatables": {
      "datatable": {
        "enabled": true,
        "autoimport": {
          "datatables.net-dt/css/dataTables.dataTables.min.css": true,
          "datatables.net-bs5/css/dataTables.bootstrap5.min.css": false
        }
      }
    }
  }
}

{
  "controllers": {
    "@pentiminax/ux-datatables": {
      "datatable": {
        "enabled": true,
        "autoimport": {
          "datatables.net-dt/css/dataTables.dataTables.min.css": false,
          "datatables.net-bs5/css/dataTables.bootstrap5.min.css": true
        }
      }
    }
  }
}

{
  "controllers": {
    "@pentiminax/ux-datatables": {
      "datatable": {
        "enabled": true,
        "autoimport": {
          "datatables.net-dt/css/dataTables.dataTables.min.css": false,
          "datatables.net-bs4/css/dataTables.bootstrap4.min.css": true
        }
      }
    }
  }
}

With Webpack Encore

Import the CSS directly in your entry file:

// assets/app.js — enable exactly one:
import 'datatables.net-dt/css/dataTables.dataTables.min.css'
// import 'datatables.net-bs5/css/dataTables.bootstrap5.min.css'

Supported Frameworks

Framework Setup

The bundle ships with the dt and bs5 packages pre-registered in the importmap. For any other framework, you need to install the required packages first.

DataTables Default

No extra setup. Works out of the box.

Bootstrap 5

Included by default. Make sure Bootstrap 5 CSS is also loaded in your application.

Bootstrap 4

php bin/console importmap:require datatables.net-bs4

Bootstrap 3

php bin/console importmap:require datatables.net-bs

Installing Extension Packages

Each extension (Select, Responsive, Buttons, etc.) also has framework-specific packages. If you use extensions, install the matching variants alongside the core package.

For example, with Bootstrap 4:

php bin/console importmap:require datatables.net-bs4
php bin/console importmap:require datatables.net-select-bs4
php bin/console importmap:require datatables.net-responsive-bs4
php bin/console importmap:require datatables.net-buttons-bs4
# Add other extensions you use…

The naming pattern is always datatables.net-{extension}-{key}.

Customising the Table Element

Override the default CSS classes applied to the <table> element globally in config/packages/data_tables.yaml:

data_tables:
  template_parameters:
    class: 'table table-striped table-hover'

Or per table in Twig:

{{ render_datatable(table, {'class': 'table table-bordered table-sm'}) }}

Tailwind Theme

The bundle ships an optional Tailwind theme, inspired by Filament: a card-shaped table with ring outlines, an amber accent, drawn pagination chevrons and a matching dark mode.

It is plain CSS built on custom properties — no Tailwind build step is required, so it behaves identically under AssetMapper, Webpack Encore and Vite. It layers on top of the default dt stylesheet, which must stay enabled.

Enabling It

{
  "controllers": {
    "@pentiminax/ux-datatables": {
      "datatable": {
        "enabled": true,
        "autoimport": {
          "@pentiminax/ux-datatables/dist/styles/datatables-base-style.css": true,
          "@pentiminax/ux-datatables/dist/styles/datatables-tailwind-theme.css": true,
          "datatables.net-dt/css/dataTables.dataTables.min.css": true
        }
      }
    }
  }
}

// assets/app.js
import 'datatables.net-dt/css/dataTables.dataTables.min.css'
import '@pentiminax/ux-datatables/dist/styles/datatables-base-style.css'
import '@pentiminax/ux-datatables/dist/styles/datatables-tailwind-theme.css'

No PHP configuration is needed. The theme declares --dt-tw-theme: tailwind on :root, and the Stimulus controller reads that custom property to select the matching column style adapter — so ChoiceColumn badges and BooleanColumn switches follow the theme instead of emitting Tailwind utilities.

The controller also moves the search label into the input’s placeholder, so the toolbar keeps the export buttons on the left and the search field on the right of a single row. The label element stays in the DOM, visually hidden, as the input’s accessible name. Set DataTables’ language.searchPlaceholder yourself and the theme leaves your value alone.

Actions rendered by Action::delete(), ::edit() and ::detail() keep their Bootstrap class names, which the theme restyles as soft-tinted chips. An action with a custom className is left untouched.

Rebranding

Reassign the accent tokens after the theme import. Values are space-separated RGB channels, which is what lets the theme derive tints and rings from a single hue:

/* The theme's default amber, swapped for indigo. */
:root {
  --dt-tw-primary-400: 129 140 248;
  --dt-tw-primary-500: 99 102 241;
  --dt-tw-primary-600: 79 70 229;
  --dt-tw-primary-700: 67 56 202;
  --dt-tw-on-primary: 255 255 255;
}

The same pattern applies to --dt-tw-gray-*, the semantic --dt-tw-success / --dt-tw-warning / --dt-tw-danger / --dt-tw-info tokens, and the --dt-tw-radius-* scale.

Dark Mode

The theme follows prefers-color-scheme, and honours an explicit choice from .dark, [data-theme="dark"] or [data-bs-theme="dark"] on <html> — so it works with Tailwind’s class strategy and with Bootstrap’s colour modes without extra configuration.

Column Chrome (Badges & Switches)

ChoiceColumn badges and BooleanColumn switches do not hard-code a single CSS framework. The Stimulus controller resolves a column style adapter from the same detected DataTables stylesheet used for the core library:

PHP APIs stay framework-agnostic: pass semantic variants such as success or danger to renderAsBadges(). The adapter maps them to the appropriate classes at render time.

Tailwind apps

1. Keep the DataTables default CSS enabled (datatables.net-dt) — there is no official DataTables Tailwind package yet.
2. Ensure Tailwind scans the compiled Stimulus bundle (or safelist the utilities) so badge/switch classes are not purged. With Tailwind v4 you can add something like:

@source "../../vendor/pentiminax/ux-datatables/assets/dist/**/*.js";

3. Semantic variants map as follows:

The adapter registry is extensible — custom adapters can be registered for other themes later. The edit modal uses a separate adapter system and is not covered by this column chrome layer.

Troubleshooting

“No DataTables stylesheet detected”

If you see this warning in the browser console, it means no recognised DataTables CSS file was found in the page’s loaded stylesheets. The bundle falls back to the dt theme.

Common causes:

• The CSS entry in controllers.json is set to false for all entries
• The CSS file failed to load (check the Network tab for 404s)
• The stylesheet is loaded after Stimulus initialises (ensure CSS loads in <head>)

Styles look wrong after switching frameworks

1. Make sure only one CSS entry is enabled in controllers.json
2. Clear the Symfony cache: php bin/console cache:clear
3. For AssetMapper, reimport assets: php bin/console asset-map:compile

Extension styling doesn’t match the framework

Each extension must use its framework-specific package. If the extension JS and CSS packages don’t match your active framework, you’ll see styling inconsistencies. Re-run importmap:require for the correct -{key} variants.