Tablar Laravel Package

Getting Started

Tablar is not a component library you sprinkle into existing views — it is a dashboard preset. Installing it replaces (or establishes) your authenticated layout, auth screens, and asset pipeline. Treat the install as a one-way-ish decision on a fresh app, and as a careful merge on an existing one.

Minimum viable path (Laravel 11/12/13, PHP 8.3+):

composer require takielias/tablar
php artisan tablar:install              # add --with-auth if you want Tablar's auth views + routes
php artisan migrate                     # only needed with --with-auth
npm install && npm run build            # Vite 8; Node 20.19+ or 22.12+

Where to look first, in this order:

1. config/tablar.php — the control plane. Layout selection, condensed/sticky-top behaviour, dark mode defaults, and (in current versions) the menu definition. Read it top to bottom before writing any Blade.
2. routes/web.php — the installer appends the auth route include and a /home route. Verify exactly what got appended before you start adding your own routes.
3. resources/views/vendor/tablar/ — the published views. This is where the menu partial, topbar, sidebar and layout files actually live; the config only feeds them.
4. The branch matching your Laravel major on GitHub. The README explicitly says docs live per-branch (12.x, 11.x, 10.x), and the live docs site is the only real reference beyond the config file's comments.

First use case worth shipping: log in, land on /home, and add two menu entries — one flat, one nested dropdown — each pointing at a named route with a Tabler icon. That single exercise touches every mechanism you will use daily: config, view publishing, route naming, active-state detection, and asset build.

Note the dependency direction: Tablar itself is the shell. Real UI widgets (cards, forms, tables, modals) come from Tabler core CSS classes directly or from the companion package tablar-kit. Plan for one of those; the preset alone will not build you a CRUD screen.

Implementation Patterns

Layout inheritance is the primary contract. Pages extend a Tablar layout rather than composing widgets:

@extends('tablar::layouts.app')   {{-- confirm the exact path in your version --}}

@section('content')
    <div class="page-header">...</div>
    <div class="card">...</div>
@endsection

The 11.2 release added per-page layout selection from the Blade file, so a page can opt into a horizontal or condensed shell without changing global config. Reach for that instead of overriding the config per request.

Menu definition — the day-to-day workflow. Menus are declared as a nested array (config or the published menu partial, depending on version) with title, icon, route/url, and children. The pattern that scales:

• Give every entry a route name, never a hardcoded URL — active-state highlighting and route:list sanity checks both depend on it.
• Keep menu construction in one place (config for static menus, a service provider or view composer for dynamic ones), and never duplicate it into layouts.
• For role/permission-aware menus, resolve the array once per request and cache it:

// app/Providers/AppServiceProvider.php  (illustrative)
View::composer('tablar::partials.menu.*', function ($view) {
    $view->with('menu', cache()->remember(
        'menu.'.auth()->id(),
        now()->addMinutes(10),
        fn () => MenuBuilder::for(auth()->user())
    ));
});

Bust that cache on role/permission changes, or you will ship a menu that lies after an admin demotes someone.

Icons. Tabler ships an icon font (ti ti-dashboard style classes). Icons are referenced by class string in the menu array. If icons vanish after an upgrade, the fix is almost always npm install && npm run build — 12.03 was specifically a tabler-icon-font fix.

Dark mode. Do not hardcode colours. Style against Tabler's CSS custom properties / the data-bs-theme attribute so your custom cards and tables invert correctly. If you need the user's preference to persist, back it with a column on users and set the attribute server-side rather than relying purely on the JS toggle — otherwise you get a flash of wrong theme on every page load.

Livewire. Officially supported since 11.2. Use full-page components (Route::get('/x', Component::class)) so they render inside the Tablar layout, add @livewireStyles/@livewireScripts to the layout once, and prefer wire:navigate for the snappy feel Tabler's chrome implies.

Custom view path instead of vendor edits. Set views_path in config/tablar.php (added in 4.8) to point at your own directory, e.g. 'views_path' => 'resources/views/admin/tablar'. This lets you diverge from vendor views without the published files being clobbered on the next publish — a much cleaner long-term position than editing resources/views/vendor/tablar in place.

Auth scaffolding decision. Use --with-auth or an existing Breeze/Fortify/Jetstream install — not both. The 13.01 line dropped the deprecated laravel/ui in favour of self-contained Breeze-inspired scaffolding, so a mixed install means two sets of routes fighting over /login and /register.

Gotchas and Tips

The installer mutates routes/web.php. tablar:export-auth used to append the auth route include and the /home route every run, leaving duplicates (fixed in 13.8.0). Even on fixed versions, git diff routes/web.php immediately after install is the cheapest insurance you'll buy all week.

Pin the version line to your Laravel major. Docs and behaviour are branch-scoped. If you're on Laravel 12, read the 12.x README; the root README is a version router, not documentation. When upgrading Laravel, budget for a matching Tablar bump in the same PR.

Rebuild assets after every package upgrade. This is a Vite/Node project, not a runtime-only package. A composer update that moves Tablar without a subsequent npm install && npm run build leaves you on stale CSS/JS — the classic symptom is a broken layout or missing icons after an otherwise innocent dependency bump.

Clear config cache after touching tablar.php. php artisan config:clear (or optimize:clear). Sticky-top toggles and view paths that "don't take effect" are almost always this.

Nested dropdowns collapsing on active children was a real bug fixed in 12.07. If your nav uses sub-menus with active descendants, floor your version at 12.07 or verify the behaviour manually.

Don't fight the preset. It gives you a shell, auth screens, menu plumbing and error-page layout (11.4) — not policies, not a table builder, not a form kit. Authorization, filtering, exports and validation all remain your application code. Teams that expect a "Laravel admin generator" end up writing wrappers around Blade partials; teams that treat Tablar as layout + menu + theme and reach for tablar-kit for widgets move much faster.

Keep overrides thin. The maintainer ships frequent patch releases (4.x → 13.x with many small fixes). Every line you change in a published view is a line you re-apply on upgrade. Prefer views_path + a wrapper layout that adds your topbar widgets, over copying and editing the vendor layout wholesale.

Debugging checklist when something renders wrong:

php artisan route:list | grep -E 'login|home'   # duplicate auth routes?
php artisan view:clear                          # stale compiled Blade
php artisan config:clear                        # stale tablar.php
grep -rn "menu" config/tablar.php resources/views/vendor/tablar | head -20

Then confirm the build actually ran: a public/build/manifest.json timestamp older than your last composer update is a smoking gun.

Extension points, ranked by durability: (1) views_path + your own layout wrapper, (2) view composers for dynamic menus, (3) the menu config array, (4) editing published vendor views — last resort, and document it in the repo so the next upgrade doesn't silently regress.