Styling

The bundle supports 7 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-bm/css/dataTables.bulma.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'
// import 'datatables.net-bm/css/dataTables.bulma.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

Bulma

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

Zurb Foundation

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

jQuery UI

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

Semantic UI

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

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 Bulma:

php bin/console importmap:require datatables.net-bm
php bin/console importmap:require datatables.net-select-bm
php bin/console importmap:require datatables.net-responsive-bm
php bin/console importmap:require datatables.net-buttons-bm
# 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'}) }}

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.