README

A Symfony bundle that renders a server-driven DataTables 3 table from an API Platform collection endpoint, using Twig Components and Stimulus.

API Grid now requires survos/grid-bundle and extends its GridController. Grid owns DataTables core (currently 3.1.3), the Bootstrap 5 / Tabler styling, extension pins, initialization and teardown. API Grid owns the API Platform requests, server-side pagination, facets, filters, selection actions and browser-side Twig rendering. Both render HTML tables; choose base Grid for in-memory rows or a single JSON fetch.

Key features:

Zero-config column inference from PHP attributes (#[Field], #[ApiFilter])
ColumnControl — per-column sort / search / facet dropdowns (default)
SearchBuilder — modal query builder with AND/OR logic
Responsive, multi-row select, bulk actions, offcanvas detail panel
Custom cell rendering via inline Twig blocks (server-side Twig, zero JS templating required)
Bootstrap 5 / Tabler-compatible out of the box

Requirements

PHP 8.5+
Symfony 8.1+ for the shared Grid dependency
API Platform 4.1+ or 5.x
survos/grid-bundle and survos/field-bundle (installed as dependencies)

Install

composer req survos/api-grid-bundle

Assets are registered via Symfony UX and AssetMapper. The canonical package names are @survos/api-grid-bundle and @survos/grid-bundle; remove obsolete application overrides using @survos/api-grid or @survos/grid. Do not run importmap:require @survos/api-grid.

{
  "controllers": {
    "@survos/api-grid-bundle": {
      "api-grid": {"enabled": true, "fetch": "lazy", "autoimport": {}}
    },
    "@survos/grid-bundle": {
      "grid": {"enabled": true, "fetch": "lazy", "autoimport": {}}
    }
  }
}

Run php bin/console importmap:install after upgrading and clear the application cache. DataTables pins come from Grid's symfony.importmap manifest. Reconcile stale application pins with that manifest; changing npm dependencies alone does not update Flex importmaps.

Core CSS is imported by the controller. Extensions and their CSS load only when the selected grid features require them. Remove old global DataTables CSS autoimports from application controller configuration. Detail dialogs reuse window.bootstrap when supplied by the host or import Modal / Offcanvas from the host's @tabler/core; Tabler does not create that global itself.

The unqualified <twig:item_grid> component now belongs to Grid. Use <twig:api_item_grid> for API Grid's legacy recursive detail component. API Grid retains its richer Column metadata and API-specific components.

Verification status

The shared base is exercised by Showcase's /browse page over 23 Site entities. Search, sorting, pagination, page-size changes and navigation away/back passed locally on October 4, 2026. That page uses <twig:grid> and does not prove API-backed behavior. Tree-demo's /playground/topics provides Grid and Grid + Responsive comparisons; its existing /topic/index is the API Grid follow-up target.

The shared PHP suite passes 10 tests / 116 assertions, and the JavaScript suite passes six tests covering lazy assets, disconnect/reconnect and API controller inheritance. Live API pagination, facets and detail dialogs still need application smoke tests after publication. See Grid's docs/testing.md and docs/upgrading.md in the mono repository for the full checks and migration notes.

Quick Start

This four-step setup gives you a working sortable, searchable, filterable grid.

1. Annotate the entity

Add API Platform filters to the entity. The bundle reads these annotations to infer which columns are sortable, searchable, and filterable without any explicit column configuration.

// src/Entity/Video.php

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\ApiFilter;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Doctrine\Orm\Filter\OrderFilter;
use Survos\ApiGridBundle\Api\Filter\MultiFieldSearchFilter;
use Survos\ApiGridBundle\Api\Filter\FacetsFieldSearchFilter;

#[ApiResource]
#[GetCollection(name: self::COLLECTION_ROUTE)]
#[ApiFilter(OrderFilter::class, properties: ['title', 'year'])]
#[ApiFilter(MultiFieldSearchFilter::class, properties: ['title', 'description'])]
#[ApiFilter(FacetsFieldSearchFilter::class, properties: ['genre', 'status'])]
class Video
{
    public const COLLECTION_ROUTE = 'api-video';
    // ...
}

If you use survos/field-bundle, annotate properties instead — see Field-Bundle Integration.

2. Compute the collection URL in the controller

Resolve the URL server-side so the template gets a plain string. This keeps the Twig template simple and makes debugging straightforward (the URL is visible in the browser network tab).

// src/Controller/VideoController.php

use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\IriConverterInterface;
use App\Entity\Video;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

class VideoController extends AbstractController
{
    #[Route('/videos', name: 'app_video_browse')]
    public function browse(IriConverterInterface $iriConverter): Response
    {
        return $this->render('video/browse.html.twig', [
            'class'               => Video::class,
            'apiGetCollectionUrl' => $iriConverter->getIriFromResource(
                Video::class,
                operation: new GetCollection(name: Video::COLLECTION_ROUTE)
            ),
        ]);
    }
}

3. Render the grid in Twig

{# templates/video/browse.html.twig #}

{% set columns = [
    col('id'),
    col('year', sortable: true),
    col('title', searchable: true, sortable: true),
    col('genre', browsable: true),
    col('status', browsable: true),
] %}

<twig:api_grid
    :class="class"
    :apiGetCollectionUrl="apiGetCollectionUrl"
    :columns="columns"
    :caller="_self"
/>

The col() Twig function is provided by the bundle. Each call returns a Column object. Arguments map directly to Column properties — see Column Reference.

4. Enable client-side pagination

DataTables uses limit/offset (not page). The bundle ships a SlicePaginationExtension that handles this, but API Platform must allow client control:

# config/packages/api_platform.yaml
api_platform:
  collection:
    pagination:
      client_items_per_page: true
      client_enabled: true

Entity Setup

Sorting

#[ApiFilter(OrderFilter::class, properties: ['title', 'year', 'createdAt'])]

Global search

The Stimulus controller sends the search box value as individual field parameters (one per searchable column). For a single unified ?search= parameter, use MultiFieldSearchFilter:

#[ApiFilter(MultiFieldSearchFilter::class, properties: ['title', 'description', 'tags'])]

Facet filters (ColumnControl / SearchBuilder)

#[ApiFilter(FacetsFieldSearchFilter::class, properties: ['genre', 'status', 'country'])]

Columns marked browsable: true use this filter. In ColumnControl mode they render as searchable dropdowns; in SearchBuilder mode they appear as criteria fields.

Field-Bundle Integration

If survos/field-bundle is installed, add #[Field] to entity properties instead of #[ApiFilter]. The bundle reads FieldDescriptor objects from FieldReader and uses them as the authoritative source for column settings.

use Survos\FieldBundle\Attribute\Field;
use Survos\FieldBundle\Enum\Widget;

class Video
{
    #[Field(searchable: true, sortable: true)]
    public string $title;

    #[Field(sortable: true)]
    public int $year;

    #[Field(filterable: true, widget: Widget::Select)]
    public string $genre;

    #[Field(filterable: true, widget: Widget::Boolean)]
    public bool $published;
}

#[Field] drives: searchable, sortable, browsable (via filterable + widget), visible, width, widget.

Explicit col() arguments always override #[Field] defaults. See Field-Bundle Integration for the full layering rules.

Twig Component Reference

<twig:api_grid
    :class="class"                   {# FQCN of the entity #}
    :apiGetCollectionUrl="url"       {# Collection endpoint URL #}
    :columns="columns"               {# array of col() objects or plain arrays #}
    :caller="_self"                  {# enables inline <twig:block> rendering #}
    columnControl=true               {# enable ColumnControl (default: false) #}
    searchBuilder=true               {# enable SearchBuilder (default: false) #}
    :pageLength="50"                 {# rows per page (default: 50) #}
    :defaultOrder="'year:desc'"      {# initial sort; "field:dir" or "a:asc,b:desc" #}
    :showRoute="'app_video_show'"    {# route name → opens detail in offcanvas panel #}
    select=true                      {# prepend checkbox column for multi-select #}
    :bulkActions="bulkActions"       {# array of bulk-action definitions #}
    :filter="filter"                 {# initial filter values, merged into API params #}
    :buttons="buttons"               {# extra toolbar buttons #}
    :scrollY="'70vh'"               {# table body height (CSS value) #}
    :tableId="'my-table'"           {# HTML id for the <table> element #}
/>

Column Reference

col(
    'fieldName',          {# positional: property name in the serialized API response #}
    title: 'Label',       {# header label (defaults to property name) #}
    sortable: true,       {# enable column ordering #}
    searchable: true,     {# include in global search #}
    browsable: true,      {# expose as a facet/filter in ColumnControl or SearchBuilder #}
    visible: true,        {# show column by default (false = hidden, toggleable) #}
    width: '10rem',       {# CSS width hint #}
    widget: 'range',      {# widget hint: text | select | range | date | boolean #}
    route: 'app_video_show',      {# wrap cell value in <a href="..."> using js-twig browser routing #}
    responsivePriority: 1,        {# DataTables responsive priority (lower = higher priority) #}
    titleAttr: 'Tooltip text',    {# HTML title attribute on the <th> #}
    order: 10,            {# display order within the column list #}
    condition: true,      {# false removes the column entirely (useful with variables) #}
)

Columns can also be passed as plain arrays (backward compatible):

{% set columns = [
    'id',
    {name: 'title', sortable: true, searchable: true},
    {name: 'status', browsable: true},
] %}

Widget Modes

The grid supports two filter UI modes. See docs/widgets.md for full documentation.

ColumnControl (recommended)

Per-column dropdowns embedded directly in the column headers. Ideal when the page already has a sidebar (e.g. EasyAdmin, Tabler).

<twig:api_grid ... columnControl=true />

Browsable columns (browsable: true) render as searchable dropdown lists.
Columns with widget: 'range' render as min/max number inputs.

SearchBuilder

A modal query builder with AND/OR logic. Browsable columns appear as criteria fields.

<twig:api_grid ... searchBuilder=true />

Custom Cell Rendering

Pass :caller="_self" and add <twig:block name="fieldName"> blocks to override rendering for specific columns. The variable row contains the full deserialized API response row.

{% set columns = [
    col('youtubeId'),
    col('title', sortable: true),
    col('year', sortable: true),
] %}

<twig:api_grid
    :class="class"
    :apiGetCollectionUrl="apiGetCollectionUrl"
    :columns="columns"
    :caller="_self"
>
    <twig:block name="youtubeId">
        <a target="_blank" href="https://youtube.com/watch?v={{ row.youtubeId }}">
            <img src="{{ row.thumbnailUrl }}" height="60" alt="{{ row.title }}"/>
        </a>
    </twig:block>
</twig:api_grid>

Blocks are compiled server-side by the js-twig-bundle Twig-to-JS bridge and executed in the browser by the Stimulus controller, so you can use Symfony Twig functions (path(), asset(), trans(), etc.) inside the blocks.

Row Actions

Add a non-searchable _actions column and render it with a <twig:block>:

{% set columns = [
    col('title'),
    col('status', browsable: true),
    col(name: '_actions', title: '', sortable: false, searchable: false),
] %}

<twig:api_grid :class="class" :apiGetCollectionUrl="apiGetCollectionUrl"
               :columns="columns" :caller="_self">
    <twig:block name="_actions">
        <a class="btn btn-sm btn-outline-secondary"
           href="{{ path('app_video_show', row.rp) }}">View</a>
        <a class="btn btn-sm btn-outline-primary"
           href="{{ path('app_video_edit', row.rp) }}">Edit</a>
    </twig:block>
</twig:api_grid>

row.rp contains the route parameters exposed in the serialized API response. Include the rp property in the entity's serialization group.

Stimulus helpers work too:

<twig:block name="_actions">
    <button {{ stimulus_action('modal-form', 'open', 'click', {
        url: path('app_video_edit', row.rp)
    }) }} class="btn btn-sm btn-outline-primary">Edit</button>
</twig:block>

Offcanvas Detail Panel

Pass showRoute to add a "View" button per row. Clicking it fetches the route and renders the HTML in a Bootstrap Offcanvas panel — no page navigation.

<twig:api_grid ... :showRoute="'app_video_show'" />

The route receives row.rp as parameters. Add ?_page_content_only=1 handling in the controller/template to return only the content fragment.

Bulk Actions

Enable select=true and define bulkActions to let users select rows and POST their IDs to a server endpoint.

// in your controller
$bulkActions = [
    [
        'id'             => 'publish',
        'label'          => 'Publish selected',
        'url'            => $this->generateUrl('app_video_bulk_publish'),
        'destructive'    => false,
        'confirm'        => true,
        'confirmMessage' => 'Publish {count} video(s)?',
    ],
    [
        'id'          => 'delete',
        'label'       => 'Delete selected',
        'url'         => $this->generateUrl('app_video_bulk_delete'),
        'destructive' => true,
        'confirm'     => true,
    ],
];

<twig:api_grid
    :class="class"
    :apiGetCollectionUrl="apiGetCollectionUrl"
    :columns="columns"
    select=true
    :bulkActions="bulkActions"
    :entityClass="class"
/>

The controller receives ids[] (array of entity IDs) and className (FQCN) as a POST form submission. A CSRF token is included automatically.

Admin Browser

A generic admin browser route is registered at /admin/browse/{code}. The code is derived from the bundle/app prefix plus the entity short name:

Survos\OutreachBundle\Entity\Contact → /admin/browse/outreach_contact
App\Entity\Video → /admin/browse/app_video

/admin/browse lists all registered Doctrine entities.

If a route named {code}_show exists, the browser passes it as showRoute, enabling the offcanvas detail panel automatically.

Backend Filters

Repository facet counts

Facet counts (shown in ColumnControl dropdowns) require a repository method that can count distinct values per field. Install the trait from survos/core-bundle:

use Survos\CoreBundle\Traits\QueryBuilderHelperInterface;
use Survos\CoreBundle\Traits\QueryBuilderHelperTrait;

class VideoRepository extends ServiceEntityRepository implements QueryBuilderHelperInterface
{
    use QueryBuilderHelperTrait;
}

Pagination

The bundle's SlicePaginationExtension translates limit/offset from the DataTables request into Doctrine range queries. This runs automatically when the bundle is installed.

survos / api-grid-bundle

Package info

Security

Fund package maintenance!

Statistics