Customize the panel
Change the admin's style preset, colours, fonts, dark mode, layout, header, sidebar, logo, favicon and interface text, and know which host file each change lives in.
The panel class decides what the admin is: its URL prefix, guard, pages and the shell settings around them. How the admin looks is split across a few files that admin:install published into your app. You own all of them. Nothing on this page needs a fork of either package.
| You want to change | Where | File |
|---|---|---|
| Component style: sizes, spacing, radii, shadows | PanelConfig::stylePreset() | your Panel class |
| Colours, radius, fonts | CSS variables and the Tailwind theme | resources/css/admin.css |
Web fonts, first-paint theme, <head> | The Blade root view | resources/views/admin.blade.php |
| Custom blocks, fields, icons, badge colours, tab title | Client registrations in the admin entry | resources/js/admin.tsx |
| Navigation layout, content width, density, dark mode policy, brand, logo, favicon | PanelConfig methods | your Panel class |
| Header, sidebar, footer, logo | A Chrome subclass | e.g. app/Admin/AdminChrome.php |
| Interface text (button labels, messages) | Laravel translation overrides | lang/vendor/tbtop-admin/{locale}/admin.php |
How the styles are built
The client package does not ship compiled CSS. @tbtop/inertia-admin/styles.css is a Tailwind v4 source file. Your Vite build compiles it, through the stylesheet the installer published:
@import '@tbtop/inertia-admin/styles.css';
@source '../../app/**/*.php';admin.tsx imports this file, and admin.blade.php loads admin.tsx. This has two consequences:
- Everything you add to
admin.cssafter the@importline is compiled together with the package's styles. Token overrides,@themechanges and your own rules all go there. - Tailwind only generates classes it finds in scanned files. The
@sourceline covers classes you write in PHP, such as a section'sclassoption. If you write admin classes somewhere else, add one@sourceline per directory. See Deploy for the build-time side of this.
The main app's resources/css/app.css and its Tailwind config do not reach the panel. The panel is its own Vite entry with its own stylesheet.
Style preset
The admin's components follow the styles of shadcn/ui's create page: Vega, Nova, Maia, Lyra, Mira, Luma, Sera and Rhea. A style shapes sizes, spacing, radii and shadows. It does not set colours, which stay in your tokens. Pick one on the panel; vega is the default:
return $panel->stylePreset('lyra');An unknown name throws. The style is applied through a class on <html>, such as style-preset-lyra, so dialogs and menus rendered in portals get it too. The admin.blade.php that admin:install publishes writes that class on the server:
<html lang="…" class="{{ request()->cookie('tbtop_theme') === 'dark' ? 'dark' : '' }} {{ \Tbtop\Admin\Panels\CurrentPanel::current()?->stylePresetClass() }}">A root view published before v0.7.2 lacks the second expression. Add it. Without it the client still sets the class once it mounts, but the first paint is unstyled.
@tbtop/inertia-admin/styles.css ships all eight styles. To compile only the one you use, import its own file instead, and keep stylePreset() on the same name:
@import '@tbtop/inertia-admin/styles/lyra.css';Applying a preset from the create page
A preset built on the create page has more parts than the style. Each goes to its own place:
| Preset part | Where it goes |
|---|---|
| Style | stylePreset() on the panel |
| Theme: base colour, theme colour, chart colour, radius, menu accent | the :root and .dark blocks in admin.css, see Colours |
| Font and heading font | --font-sans and --font-heading, see Fonts |
| Icon library, menu colour | not supported: the admin uses lucide icons and the default menu colour |
Overriding a style
Every layer of a style stays yours to change:
- Tokens and theme variables (
--primary,--radius,--spacing…). The styles read them and never set them. - One element. A utility class wins: the styles sit in Tailwind's
componentslayer, belowutilities. - One component everywhere. Any unlayered rule in
admin.cssbeats the style, for example.cn-button { border-radius: 9999px; }. Thecn-*class names are upstream shadcn's.
Colours
The admin is drawn with shadcn-style design tokens: CSS variables such as --primary and --border, mapped to Tailwind colours (bg-primary, border-border). The package defines a light set on :root and a dark set on .dark. To re-theme, redefine the variables below the @import. Your rules come later in the compiled file, so they win.
@import '@tbtop/inertia-admin/styles.css';
@source '../../app/**/*.php';
:root {
--primary: oklch(0.546 0.245 262.881);
--primary-foreground: oklch(0.985 0 0);
--ring: oklch(0.623 0.214 259.815);
}
.dark {
--primary: oklch(0.707 0.165 254.624);
--primary-foreground: oklch(0.205 0 0);
--ring: oklch(0.546 0.245 262.881);
}Override only the tokens you change. The rest keep the package values. A palette from a shadcn theme generator works the same way: paste its :root and .dark value blocks and leave out its @import and @theme inline lines, which the package already has.
The tokens the package defines at v0.8.1:
| Token | Used for |
|---|---|
--background, --foreground | Page and shell background, body text. The sidebar is drawn with these too. |
--card, --card-foreground | Cards and card-variant sections |
--popover, --popover-foreground | Dropdowns, menus, popovers |
--primary, --primary-foreground | Primary buttons, links in rich text, primary badges |
--secondary, --secondary-foreground | Secondary buttons |
--muted, --muted-foreground | Muted surfaces, helper and placeholder text, gray badges |
--accent, --accent-foreground | Hover states and the active navigation item |
--destructive, --destructive-foreground | Danger buttons, validation errors, danger badges |
--success, --warning, --info and their -foreground pairs | Status badges and icons in tables, trends on stat cards, and the tinted displayAlert variants (danger uses --destructive) |
--border, --input, --ring | Borders, input borders, focus rings |
--chart-1 … --chart-5 | Chart series |
--chart-success, --chart-warning, --chart-danger | Trend lines on stat cards |
--sidebar, --sidebar-foreground, --sidebar-primary, --sidebar-accent, --sidebar-border, --sidebar-ring and their pairs | Defined for shadcn compatibility. At v0.8.1 the stock shell uses only --sidebar-foreground, as the hover colour of a collapsible navigation group's label. |
The sidebar follows --background
Changing --sidebar has no visible effect at v0.8.1: the stock sidebar uses --background and --border, and the active item uses --accent. The sidebar's frame is not part of the chrome tree, and at v0.8.1 no token or panel setting tints it separately: the frame takes --background.
Radius
--radius (default 0.5rem) is the base step. Tailwind's rounded-xs through rounded-xl are derived from it, so one variable rounds every control:
:root {
--radius: 0.75rem;
}The package defines --radius on :root only, so the dark theme uses the same value.
Badge and icon colours in tables
Table badges and icon columns take a colour name: gray, primary, success, warning, danger, info (also available as the Color enum). A name those do not cover can be registered in the client. Pass Tailwind classes for the badge background, the text on it, and optionally the colour of a bare icon:
import { registerTableColor } from "@tbtop/inertia-admin";
registerTableColor("violet", { bg: "bg-violet-600", text: "text-white", icon: "text-violet-600" });Column::make('tier')->badge([
'vip' => ['label' => 'VIP', 'color' => 'violet'],
'standard' => ['label' => 'Standard', 'color' => 'gray'],
]),Write the class names out in full, as above. Tailwind finds classes by scanning source text, so a class built from a string at runtime is not generated. An unknown colour name falls back to the gray styling.
Fonts
The stock admin.blade.php puts Tailwind's font-sans class on <body>, so the admin font is Tailwind's --font-sans theme variable. Load the font in the root view and set the variable in admin.css:
<head>
{{-- ... --}}
<link rel="preconnect" href="https://fonts.bunny.net">
<link href="https://fonts.bunny.net/css?family=inter:400,500,600" rel="stylesheet" />
{{-- ... --}}
</head>@theme {
--font-sans: 'Inter', ui-sans-serif, system-ui, sans-serif;
}Card titles and the table's empty-state heading use --font-heading, which falls back to --font-sans. It is not a Tailwind theme variable, so set it on :root:
:root {
--font-heading: 'Inter Tight', ui-sans-serif, system-ui, sans-serif;
}--font-mono works the same way as --font-sans for monospace text. A self-hosted font works too: declare it with @font-face in admin.css and name it in --font-sans.
Dark mode
Dark mode is class-based: the .dark class on <html> switches every token to its dark value. The chosen theme is stored in a tbtop_theme cookie with the value light, dark or system. Two panel settings control it:
$panel
->darkMode(true) // false: force light and hide the theme toggle
->defaultThemeMode('system'); // 'light' | 'dark' | 'system', used when there is no cookie yet-
The toggle. The stock header has no theme switch. Add
$s->themeToggle()to the header through your chrome (below). One click cycles light, dark, system. -
The first paint.
admin.blade.phphas an inline script that reads the cookie and sets.darkbefore React loads, so the page does not flash. It falls back tosystem. If you setdefaultThemeMode('dark')or('light'), change the fallback in that script to match:resources/views/admin.blade.php var theme = match ? match[1] : 'dark'; -
Light only.
darkMode(false)removes.darkonce the app mounts and hides the toggle. The Blade view still applies a saved dark cookie before that, so remove the inline script and theclassexpression on<html>as well, or users who chose dark earlier see one dark frame on every full page load.
Layout and density
These PanelConfig settings rearrange the shell. They are covered in Register a panel; in short:
$panel
->navigation('topbar') // 'sidebar' (default) | 'topbar' | 'topbar-sidebar' | 'rail-sidebar'
->maxContentWidth('7xl') // sm … 7xl, full, prose; page content is capped at 5xl otherwise
->density('compact') // 'default' | 'compact': smaller controls, tighter spacing, narrower sidebar
->stylePreset('vega'); // component style, see Style preset abovesidebarputs the logo and the navigation in a left sidebar and the header items in a top strip.topbarputs the logo and the navigation in one horizontal bar. Navigation groups become dropdowns.topbar-sidebaris a full-width top bar with a sidebar beneath it. The bar shows the brand text and a button that collapses the sidebar to an icon rail.rail-sidebarshows each navigation group as a labelled icon in a narrow rail, beside a sidebar that lists only the active group. See Rail + sidebar.
All four collapse to a drawer on small screens. The chrome you author is the same in every layout; only its arrangement changes.
A single page can leave the shell entirely: layout() returning 'center' renders it without sidebar and header, centred on the screen. Sign-in pages use this. See Pages and Authentication.
Header, sidebar and footer
The shell has three areas, and each one is a tree of ordinary DSL nodes. The default Tbtop\Admin\Panels\Chrome class builds them:
| Area | Stock content | Override |
|---|---|---|
| Header | the user menu | headerItems() to add items, header() to replace the area |
| Sidebar | the logo, then the navigation menu | sidebarItems() to add items, sidebar() to replace the area |
| Footer | nothing | footer() |
Extend it, spread the parent's items to keep them, and point the panel at your class:
<?php
namespace App\Admin;
use Tbtop\Admin\Dsl\Node;
use Tbtop\Admin\Dsl\S;
use Tbtop\Admin\Panels\Chrome;
class AdminChrome extends Chrome
{
protected function headerItems(S $s): array
{
return [
$s->notifications(),
$s->action('view-site')->label('View site')->url('/')->openUrlInNewTab(), // a same-tab url() to the same origin is an Inertia visit, and the admin bundle cannot render the site's pages
$s->themeToggle(),
...parent::headerItems($s), // the user menu, kept last so it sits at the far right
];
}
public function footer(S $s): ?Node
{
return $s->flex([
$s->displayText('Acme admin')->variant('muted'),
], justify: 'center', class: 'py-6');
}
}$panel->chrome(AdminChrome::class);The building blocks made for the shell, all on $s:
| Method | Renders |
|---|---|
logo() | The brandLogo() image, or the brand text without one, linked to the panel root |
navMenu() | The navigation built from your pages' nav() and the panel's navigationItems() |
userMenu(['locales' => false]) | The profile dropdown: user, your userMenuItems(), language switcher, sign out. The option hides the language section. |
notifications() | The notification bell (needs the notifications table, see Register a panel) |
themeToggle() | The light / dark / system switch |
localeSwitcher('dropdown') | A standalone interface-language switcher, 'buttons' by default. Hidden when the panel has no locales; with a single locale it still shows one button, so add it only when ->locales() lists two or more. |
spacer() | Pushes the following items to the far edge |
Any other node works too: flex, stack, displayText, displayImage, your own blocks. Actions in the chrome must be url() or custom() actions. A server action (->handle()) has no page endpoint to post to, so the panel throws when it serializes the chrome.
Entries in the user menu and extra navigation links are panel settings, not chrome: userMenuItems() and navigationItems(). See Navigation.
Brand, logo and favicon
brand() names the panel. Four more methods add a logo and a tab icon:
return $panel
->brand('Acme') // the name $s->logo() shows
->brandLogo(asset('images/logo.svg')) // an image instead of the name
->darkModeBrandLogo(asset('images/logo-dark.svg')) // optional, used while the admin is dark
->brandLogoHeight('2rem') // px, rem or em; default 1.5rem
->favicon(asset('favicon.svg')); // the browser-tab iconWithout brand(), the logo shows the translated nav.title string, "Tabletop" in English. With brandLogo(), $s->logo() renders the image instead, still linked to the panel root, and the brand name becomes its alt text.
- URLs are used as given. Wrap a file from
public/inasset(), or pass any absolute URL. - The dark logo follows the light / dark switch without a reload. Set on its own, without
brandLogo(), it changes nothing. - The logo shows wherever
logo()does: the sidebar, thetopbarbar, thetopbar-sidebarbar and the mobile drawer. In the narrowrail-sidebarrail, and in the collapsedtopbar-sidebarrail, it is fitted into a small square, so a square mark reads best there. brandLogoHeight()takes a px, rem or em length. Anything else throws.favicon()is set on every admin page, the way the page title is. Each panel can have its own. A panel without one keeps the icon fromadmin.blade.php.
For a logo that is more than an image, such as a mark next to styled text, put your own leaf block where logo() was. The PHP side is a node with whatever the client needs:
protected function sidebarItems(S $s): array
{
return [
new Node('app:logo', [
'src' => asset('images/mark.svg'),
'name' => config('app.name'),
'href' => url('admin'),
]),
$s->navMenu(),
];
}The client side renders it. Register it in admin.tsx before createInertiaApp():
import { Link } from "@inertiajs/react";
import { type RenderProps, registerBlock } from "@tbtop/inertia-admin";
interface LogoOptions {
src: string;
name: string;
href: string;
}
function Logo({ options }: RenderProps<LogoOptions>) {
return (
<Link href={options.href} className="flex items-center gap-2 font-semibold">
<img src={options.src} alt="" className="size-7" />
{options.name}
</Link>
);
}
registerBlock<"app:logo", LogoOptions>({ kind: "app:logo", behavior: "leaf", render: Logo });The sidebar tree is also what the topbar layout and the mobile drawer show, so the custom logo appears there too. The topbar-sidebar layout is the exception: its top bar renders the stock logo itself, brandLogo() included, and your sidebar tree sits beneath it.
Styling blocks from PHP
Layout nodes take extra Tailwind classes: the class option of stack(), row(), grid(), section() and aside(), and the class: argument of flex(). Use the theme's colour names so the result follows your tokens and dark mode:
$s->section(['title' => 'Danger zone', 'class' => 'border-destructive'], [
// ...
]);These classes are found by the @source '../../app/**/*.php' line. Classes in PHP files outside app/ need their own @source line, or they compile to nothing.
Client components and icons
Your own fields, display blocks, browser-side action handlers and icons are registered in admin.tsx and used from PHP by name. That is covered in Client components. Every Lucide icon already works by its kebab-case name. registerIcon() is only for aliases and icons of your own.
Use your own kind names (an app: prefix keeps them apart from built-ins) and place them through your chrome or pages. Replacing a built-in kind by registering the same name is not a supported extension point.
Interface text
The admin's own strings (button labels, table and form messages, the sign-in screen) come from the package's Laravel translation file, tbtop-admin::admin. The package ships English (en) and Ukrainian (uk). Override single keys with Laravel's standard vendor override:
<?php
return [
'action' => [
'logout' => 'Sign out',
],
'nav' => [
'title' => 'Acme',
],
];Laravel merges this file over the package's, so list only the keys you change. The key names are in the package's resources/lang/en/admin.php. The same path with another locale code (lang/vendor/tbtop-admin/de/admin.php) adds an interface language. Add the code to ->locales() as well; keys the file does not define fall back to English.
Browser title and loading bar
Two small settings live in the createInertiaApp() call of admin.tsx:
createInertiaApp({
title: (title) => `${title} · Acme admin`, // the <title> of every admin page
progress: {
color: "#2563eb", // Inertia's loading bar between pages
},
// resolve and setup unchanged
});The favicon is a panel setting, favicon(), see Brand, logo and favicon. Any other <head> tags go in admin.blade.php.
Reference
- Every
PanelConfigandChromemethod with its signature: API reference: Panel. - The shell building blocks and layout nodes: API reference: Builder.
- What
admin:installpublishes and the Vite setup: Install.
Register a panel
Create the panel class that owns an admin's URL prefix, guard, middleware and pages, and register it in config/tbtop-admin.php.
Authentication
Publish the sign-in, password reset, email verification and profile pages, add two-factor sign-in, send guests to them, and rely on the logout route and signed-in user the package provides.