Filament White Label Laravel Package

Getting Started

Install the package into a Filament v5 application:

composer require muazzambuilds/filament-white-label

Then publish and run any migrations the package ships, and create the public storage link if you will upload logos/favicons:

php artisan vendor:publish --tag="filament-white-label-migrations" # confirm the exact tag in the package source/README
php artisan migrate
php artisan storage:link

Register the package’s plugin or settings page in each PanelProvider you want to white-label. The exact plugin class is in the package source; registration follows normal Filament v5 plugin conventions. Do this per panel—do not assume one registration covers every panel.

Your first useful workflow should be “brand a client panel without a deploy”:

1. Open the White Label settings page in the target panel.
2. Set the brand name, light/dark logos, favicon, and logo height.
3. Set the primary color to the client’s brand color and adjust the supporting palette.
4. Pick a Bunny Font and check the live preview.
5. Add footer text/links and any small custom CSS.
6. Save, refresh the panel, and verify light/dark mode.

Where to look first: the package README, the plugin/settings page class, the migration that creates the settings table, and any config file. Because the public documentation is thin, the source is the source of truth for exact class names, table columns, publish tags, and tenant-resolution behavior.

Implementation Patterns

Treat branding as data, not code. The main value is letting an admin change brand name, logos, colors, fonts, footer, and CSS from the panel. Use that for client-specific branding instead of hard-coding values in PanelProvider or Blade. Reserve code changes for structural layout changes the package does not expose.

Panel defaults first, tenant overrides second. For a multi-tenant SaaS, configure sensible panel-level defaults and use per-tenant rows only where tenants actually need distinct branding. This avoids a large settings table and makes fallback behavior predictable when a tenant has no row yet.

Use one panel per client when isolation matters. If you run separate admin panels per client, register the plugin in each panel and configure each panel independently. This is simpler than tenant overrides and keeps settings, assets, and access control separated.

Use tenant overrides when one panel serves many tenants. Enable Filament tenancy, ensure the tenant context is resolved before the panel renders, and configure branding from the tenant’s settings page or tenant menu. Test what happens when the tenant switches, when a tenant row is missing, and when a tenant is deleted.

Map colors deliberately. Set primary to the brand color, then choose gray/danger/warning/success/info so they remain readable against the panel background. Check buttons, badges, links, charts, disabled states, and dark mode. A brand color that looks good in a logo may fail contrast as a button background.

Keep font choices constrained. Bunny Fonts is convenient and the live preview helps non-developers choose, but confirm the chosen font has the weights you use. Provide a fallback stack and test with the font blocked or offline—especially if your CSP or privacy requirements prevent third-party font loading.

Use custom CSS as a last-mile tool. The package sanitizes CSS, so use it for small adjustments: spacing, footer styling, minor border radius, or a panel-specific accent. For deep component changes, use Filament’s theme build or view overrides instead of fighting the sanitizer with large CSS blocks.

Scope CSS to the panel. Avoid global selectors and excessive !important. Target Filament’s panel body class or stable component classes. Keep a copy of production CSS snippets in your repo or runbook so you can restore them if a settings row is lost.

Handle logo and favicon assets like production assets. Upload reasonably sized SVG/PNG files, set logo height explicitly, and verify the generated URL works from the browser. If you use S3 or a non-default disk, confirm the package reads from the disk you expect. Favicons are aggressively cached—test in a private window after changing one.

Restrict who can edit settings. The package provides the settings surface, but you should still gate it with Filament policies or role checks. In tenant panels, tenant admins may edit their own branding, but platform staff should control defaults and dangerous fields like custom CSS.

Seed defaults for repeatable environments. For new panels or tenants, create a small seeder/service that writes default branding. This keeps staging and production consistent and avoids “someone configured it manually” drift.

Test the failure modes. Verify: missing logo, broken logo URL, font blocked by CSP, invalid color, empty footer, tenant without settings, tenant switch, dark mode, and a fresh panel with no settings row. The package advertises safety guards—confirm what “safe” looks like in your panel rather than assuming.

Gotchas and Tips

• Thin documentation and a young package. With v1.0.0, low stars, and no dependents, pin the version and read the source before relying on it. Check the migration, settings model, plugin class, and sanitizer behavior.
• Filament v5 only. Do not install this in a v3/v4 app and expect compatibility. Confirm your Filament constraint before adding it.
• Panel ID is likely the storage key. If you rename a panel ID or restructure panel providers, existing settings may no longer resolve. Treat panel IDs as stable identifiers.
• Tenant rows need tenant context. Per-tenant settings only make sense when Filament tenancy is enabled and the current tenant is resolved. If settings appear to be ignored, log the panel ID and tenant ID being used.
• Clear caches after changes. If branding does not update, clear Filament/config/view caches and retest. Filament panels and settings can be cached per request or deployment.
• File uploads fail silently in local dev. Check storage:link, disk configuration, file permissions, and whether the panel is generating URLs from the expected disk.
• CSS sanitization will strip things. Expect @import, remote url(), JavaScript, and some advanced CSS to be removed or rejected. If your custom CSS “does nothing,” inspect the saved value and the rendered output before assuming the selector is wrong.
• Bunny Fonts is an external dependency. CSP, offline development, GDPR/privacy reviews, and corporate networks can block it. The preview may work for you but fail for a client.
• Color contrast is your responsibility. The package can set colors; it cannot guarantee accessibility. Check dark mode and all semantic colors.
• Safety guards may fall back silently. Invalid values or missing assets may be ignored rather than throwing an error. Debug by checking the settings row, logs, and rendered panel HTML.
• Authorization is not automatic. Add a policy or gate around the settings page. Custom CSS and footer content are effectively privileged configuration.
• Footer content needs a policy. If HTML is allowed, sanitize or restrict it. If it is plain text, do not expect links to render.
• Tenant deletion cleanup. If tenant rows are stored in the package table, confirm foreign keys/cascade behavior or clean up orphaned rows in your tenant deletion flow.
• Multi-panel means multiple registrations. A common mistake is registering the plugin once and expecting global branding. Register it in every panel that needs white-labeling, and configure each panel separately.
• Extension strategy. Use the package’s settings UI and custom CSS for branding; use Filament’s theme/views for structural changes. If the package exposes config or publishable views, publish them and track changes in version control rather than editing vendor files.