Skip to main content
A page name is looked up in the active theme first, then in the default theme
A client theme is a folder in resources/js/pages/themes/. It styles the dashboard, store, tickets and sign in pages. Admin screens are not part of it, see admin themes.
Portal themes are a different thing. They change the public landing page and live under Admin, Customization, Themes.

How a theme is picked

1

Spartan scans the folder

Every folder in resources/js/pages/themes/ shows up in the list. There is nothing to register.
2

An admin picks one

Go to Settings, Appearance, Client Theme. This writes the active_theme setting.
3

Each page looks for its file

A page named client/dashboard loads themes/{active}/UI/dashboard.tsx. If that file is missing, it loads the same path in default.
Settings, Appearance, Client Theme
Auth pages follow the same rule with auth/login.tsx instead of UI/dashboard.tsx.

The bundled themes

default holds everything, quanta overrides a few pages, nodepeak only a navbar and footer
A theme with a single file is valid. Copy a bundled theme to a new folder name to start, never edit the bundled ones in place.

What you can override

In {theme}/auth/. The file name must match exactly.
A UI/ page does not need a layout. Spartan wraps it in AuthenticatedLayout, which adds the sidebar, navbar and footer. Auth pages are never wrapped.

A minimal theme

One file, one changed component. Every card in the customer area now has a thicker border and bigger corners.
1

Create the folder and file

The folder name becomes the label, so aurora shows as Aurora.
2

Write the component

Copy themes/default/components/SectionCard.tsx first so you keep its props, then change the markup.
resources/js/pages/themes/aurora/components/SectionCard.tsx
3

Build and pick it

Run the build, then choose Aurora under Settings, Appearance, Client Theme.
The default theme sign in page
The same page with the quanta theme
The two images above show the same sign in page on the default theme and on quanta. Changing a theme changes only the files it overrides.
A new theme folder needs a build, because Vite finds themes with a glob at build time. Edits to a theme that already exists are picked up by npm run dev.

Overriding components

Most shared pieces in the default theme are wrapped in withThemeOverride. A file at the same path in your theme replaces them.
The export name matters. A default export also works.
Your component gets the same props as the original. Read the default one first, or you will drop loading states and permission checks.
Paths are relative to {theme}/components/.
Overrides are only read when active_theme is not default. The loader leaves themes/default/components/ out of the on-demand bundle, so a theme’s components are fetched only while it is active.
On a Starter or Cloud license the footer must keep the DezerX watermark. If you override Footer, copy the watermark block from themes/default/components/Footer.tsx unchanged, or the site goes into maintenance mode.

Colors and corner radius

Colors and corner roundness come from settings
Use the existing classes and your theme follows light and dark mode, the Colors page and the corner setting for free.
Settings, Appearance, Corners
Corner roundness is the ui_corner_radius setting, from 0 to 200 percent with 100 as the default. It sets --radius-scale, which scales every Tailwind rounded-* class. Do not hardcode pixel radii or hex colors.
Button helpers: button-primary, button-secondary, button-success, button-warning, button-danger.
Theme pages are ordinary Inertia pages. Copy the default page you replace and keep its PageProps.
Always sanitize HTML or SVG that came from a setting before you render it.

Build and reload

A theme is frontend only, so there is nothing to reload on the server.
Octane workers pick up the new build on their own. Switching the active theme in Settings applies on the next page load. If you ever change PHP alongside, reload Octane with sudo systemctl reload dezerx-octane.
Test the pages you changed and one you did not, in light and dark mode, on a narrow screen and signed out.

Keeping a theme through updates

The updater saves your theme folders and puts them back before it rebuilds the frontend. This is on by default (--keep-themes).
A folder named like a bundled theme (default, quanta, nodepeak) is replaced by the release. Always copy to a new name.

When it does not work