Layout themes

Replace whole parts of the panel layout with a theme.

License required

Layout themes need the Theme Customization license feature.

A layout theme changes the whole appearance of the panel. It can replace complete pages, layouts, and components. A colour preset cannot do that.

Layout themes live in the Layout Themes section at the bottom of the Themes page. Navigate to Admin > Appearance > Themes and scroll to the end of the page.

You need the Manage Appearance permission to install, activate, or remove a theme.

What a layout theme can replace

A theme package can override four kinds of file:

Kind	Examples
Pages	The dashboard, the server list, the billing pages, the account pages.
Layouts	The sign-in shell, the dashboard shell, the billing shell, the support shell.
Components	The sidebar, the header, the footer, buttons, cards, badges, alerts, the console, resource graphs.
Styles	The global stylesheet, including the colour tokens of the panel.

The three example themes show the range:

• Windows 95 - a 1990s look with bevelled borders, a teal desktop, and start-menu navigation.
• Neon - a cyberpunk look with a pixel cityscape, magenta glow, and horizontal server tabs.
• Sleek - a redesign with a 60-pixel icon rail, an indigo palette, circular gauges, and light and dark modes.

WARNING

A theme that replaces the style file also replaces the colour tokens. If the author picks poor colours, some text becomes hard to read. Theme authors must check the contrast of text against every background in both light and dark states.

Installing a theme

The panel has no marketplace and no in-panel catalogue. You install a theme from a file.

1. Navigate to Admin > Appearance > Themes and scroll to Layout Themes.
2. Click Import Theme.
3. Select a .bptheme file.
4. If the theme is unsigned, read the warning dialog. Click Install Anyway to continue, or Cancel to stop.
5. Click Activate on the new theme.
6. Wait for the rebuild. It takes 30 to 60 seconds.

TIP

Install a theme only from a developer that you trust. BadgerPanel does not review an unsigned theme.

An import can report warnings. Read them before you activate the theme.

The theme list

Each theme row shows:

• The theme name and the version.
• An Active badge on the theme in use.
• A Signed badge (green) or an Unsigned badge (amber).
• The description and the author.
• The number of overridden files.

An inactive theme has an Activate button and a bin icon. The active theme has no buttons.

Reset to default

A Reset to Default button appears in the Layout Themes header, to the left of Import Theme. It appears only when a layout theme is active.

Click it to return the panel to the standard BadgerPanel layout. The panel then rebuilds.

This button is the control that you need when a theme breaks a page. It is separate from the Reset to Default button higher up the page, which returns the colours.

Removing a theme

You cannot delete the active theme. Click Reset to Default first. Then click the bin icon on the theme row.

Build status

The panel rebuilds the frontend after each activate and each reset. The page reports the state:

Message	Meaning
Theme build queued...	The panel accepted the job.
Rebuilding panel... This may take 30-60 seconds.	The build runs.
Theme activated. Rebuilding panel...	The activation succeeded and the build started.
Resetting to default theme. Rebuilding panel...	The reset succeeded and the build started.
Build failed: ...	The panel keeps the previous version.

The panel serves the previous version during a rebuild.

Colour settings with a theme active

The colour settings, the effect settings, the fonts, and the branding stay available while a layout theme is active. The theme author decides how much of that the theme uses.

For theme developers

A .bptheme file is a ZIP archive with a manifest. The manifest holds:

Field	Purpose
name and slug	The identity of the theme.
version	The theme version.
description	The text that the admin reads in the theme list.
author	The author name and an optional link.
compatibility	The lowest and highest panel version that the theme supports.
overrides	The list of files that the theme replaces.
dependencies	Extra packages. This field is optional.

A signed theme also carries a signature block.

To start, clone the Standard Theme repository. It holds the default theme files and the development guide.

Key points:

• Include only the files that you change. Every other file falls back to the default.
• The default/ theme in the repository holds every overridable file as a reference.
• All component files must be client-side React components.
• Check the text contrast of your colours before you publish.