Search by

ahmaruff / laravel-htmx-table

ahmaruff

A lightweight server-driven table for Laravel using blade and HTMX

v0.1.0 2026-11-22 07:10 UTC

This package is auto-updated.

Last update: 2026-11-22 07:40:06 UTC


README

Laravel Htmx Table

Packagist PHP from Packagist Laravel versions GitHub Workflow Status (main) Total Downloads

A lightweight server-driven table for Laravel using Blade and HTMX.

The package renders the table fragment on the server. Search, sorting, and pagination are normal Laravel query work; HTMX swaps the returned fragment into the page.

Requirements

  • PHP 8.2–8.5
  • Laravel 10–13
  • HTMX 1.9+ (2.x recommended; the package uses closest targeting)

Supported versions

PHP Laravel
8.2 10, 11, 12
8.3 10, 11, 12, 13
8.4 11, 12, 13
8.5 12, 13

Laravel 10 and 11 are end-of-life; support for them is best-effort. PHP 8.6 is not supported yet. Composer may block end-of-life Laravel versions because of known security advisories.

Installation

composer require ahmaruff/laravel-htmx-table

Publish everything at once:

php artisan vendor:publish --tag="htmx-table"

Or publish individual resources:

php artisan vendor:publish --tag="htmx-table-config"
php artisan vendor:publish --tag="htmx-table-views"
php artisan vendor:publish --tag="htmx-table-assets"
php artisan vendor:publish --tag="htmx-table-lang"

The stylesheet is published to public/vendor/htmx-table/htmx-table.css. Translations are published to lang/vendor/htmx-table.

Setup

Include HTMX and the published stylesheet in the page that hosts the table:

<link rel="stylesheet" href="{{ asset('vendor/htmx-table/htmx-table.css') }}">
<script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.11/dist/htmx.min.js"></script>

Quickstart

use Ahmaruff\HtmxTable\Column;
use Ahmaruff\HtmxTable\HtmxTable;
use App\Models\User;
use Illuminate\Http\Request;

public function index(Request $request)
{
    $table = HtmxTable::make(User::query())
        ->columns([
            Column::make('name')->searchable()->sortable(),
            Column::make('email')->searchable()->sortable(),
            Column::make('created_at')->label('Joined')->sortable(),
        ])
        ->paginate(15);

    if (HtmxTable::isFragmentRequest($request)) {
        return $table->render($request);
    }

    return view('users.index', ['table' => $table]);
}

isFragmentRequest() treats normal HTMX requests as fragments, but keeps history-restore requests as full-page requests so browser back/forward does not replace the page with a table fragment alone.

{{-- resources/views/users/index.blade.php --}}
<x-htmx-table::table :table="$table" />

The package does not decide when to return a fragment. The host application checks HtmxTable::isFragmentRequest($request) (or any other condition) and returns $table->render($request) for HTMX requests. The same table can be rendered directly with {{ $table->render() }}.

Columns

Column::make('name')          // public key and default data key
    ->label('Full name')      // optional display label
    ->dataKey('users.name')   // optional database/row access path
    ->searchable()            // include in search
    ->sortable();             // allow sorting by this column

The key is the stable identifier used in sort state and URLs. The dataKey is used for search, ordering, and reading the cell value. Dotted data keys require a join for search and sort; they do not add relation query support automatically.

Cell rendering

Cells are escaped by default. A renderer can return an Htmlable value when it intentionally produces markup:

use Illuminate\Support\HtmlString;

Column::make('status')->render(
    fn (mixed $row, mixed $value): HtmlString => new HtmlString(
        '<span class="badge">'.e($value).'</span>'
    ),
);

Returning a plain string containing HTML renders it escaped. See Security.

Search and sorting

Search is a grouped OR of LIKE conditions across columns marked searchable(). Sorting only accepts columns marked sortable(); unknown sort keys and non-sortable columns are ignored, and invalid directions fall back to asc.

Query parameter names are configurable in config/htmx-table.php:

return [
    'per_page' => 15,

    'query_params' => [
        'search' => 'search',
        'sort' => 'sort',
        'dir' => 'dir',
        'page' => 'page',
        'cursor' => 'cursor',
        'per_page' => 'per_page',
    ],

    'pagination' => [
        'on_each_side' => 2,
    ],
];

Generated URLs, the search input, and the per-page selector use the same aliases as request parsing. Query parameters unrelated to table state are preserved.

Pagination

$table->paginate(15);         // length-aware pagination with page numbers
$table->simplePaginate(15);   // previous/next only
$table->cursorPaginate(15);   // cursor pagination

paginate() renders numbered page links with ellipses. The number of pages around the current page is controlled by pagination.on_each_side.

Enable a per-page selector explicitly:

$table->perPageOptions([10, 15, 25, 50])->paginate(15);

The selector uses the configured per_page query parameter, validates the request against the allowed options, and resets the current page when changed. The table default is always included in the selector.

The mode must be selected before rendering. Cursor pagination always applies a deterministic tie-breaker (the model key, or id for query-builder sources). An invalid or expired cursor restarts from the first page.

Customization

Use classes() for per-table styling and CSS variables for colors, spacing, and radii:

$table->classes('table-compact', 'theme-dark');

For structural changes, use view() with a copied published view. view() is an escape hatch: the custom view owns the markup contract, including the htmx-table-wrapper target and swap attributes. See Custom views.

The table lives in a .htmx-table-scroll container, so the toolbar and pagination stay visible when the table overflows horizontally.

Localization

The package ships English and Indonesian translations. Use the application locale or override it per table:

$table->locale('id');
$table->searchPlaceholder('Cari user...');

Publish the language files to add a locale or change copy:

php artisan vendor:publish --tag="htmx-table-lang"

See Localization.

Multiple tables

Each fragment targets itself relative to the trigger:

hx-target="closest .htmx-table-wrapper"

That means multiple tables can share a page without ids:

<x-htmx-table::table :table="$users" />
<x-htmx-table::table :table="$orders" />

An id is optional and only needed for CSS, JavaScript, or triggers outside the table fragment:

HtmxTable::make($query)->id('users-table');

Then target it explicitly:

<button hx-get="/users" hx-target="#users-table">Refresh users</button>

Documentation

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Thank you for considering contributing to Laravel Htmx Table! Please review our contributing guide to get started.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

Laravel Htmx Table is open-sourced software licensed under the MIT license.