> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dezerx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Client themes

> Restyle the customer area by overriding only the pages and components you want. Everything else falls back to the default theme.

![A page name is looked up in the active theme first, then in the default theme](https://mintcdn.com/dezerx/W6tdUG_weSNDlVA2/public/themes/client-themes/resolve.webp?fit=max\&auto=format\&n=W6tdUG_weSNDlVA2\&q=85\&s=4ec34102a65a378c0c0170467aa5a9ae)

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](https://docs.dezerx.com/extensions/tutorials/admin-themes.md).

> [!NOTE]
>
> 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](https://mintcdn.com/dezerx/W6tdUG_weSNDlVA2/public/themes/client-themes/select.webp?fit=max\&auto=format\&n=W6tdUG_weSNDlVA2\&q=85\&s=5e64f8e168a78f8d1ef910e2b43bc06b)

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](https://mintcdn.com/dezerx/W6tdUG_weSNDlVA2/public/themes/client-themes/tree.webp?fit=max\&auto=format\&n=W6tdUG_weSNDlVA2\&q=85\&s=b9a6c42482db34d6590bb23c1ad1f8ce)

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

> [tab] Auth pages
>
> In `{theme}/auth/`. The file name must match exactly.
>
> | File | Screen |
> | - | - |
> | `login.tsx` | Sign in |
> | `register.tsx` | Sign up |
> | `ForgotPassword.tsx` | Request a reset link |
> | `ResetPassword.tsx` | Set a new password |
> | `2fa-verification.tsx` | Two factor prompt |
> | `phone-verification.tsx` | Phone verification |

> [tab] Client pages
>
> In `{theme}/UI/`. The path after `UI/` must match the page name.
>
> | File | Screen |
> | - | - |
> | `dashboard.tsx` | Dashboard |
> | `Profile.tsx` | Account settings |
> | `Inbox.tsx` | Notifications |
> | `gift-cards.tsx` | Gift cards |
> | `Cart/Index.tsx` | Cart |
> | `Market/Index.tsx` | Store front |
> | `Market/Products.tsx` | Category listing |
> | `Market/ProductDetails.tsx` | Product page |
> | `Market/Checkout.tsx` | Checkout |
> | `Invoice/Index.tsx` | Invoice list |
> | `Invoice/View.tsx` | One invoice |
> | `Service/manage.tsx` | Service overview |
> | `Service/configuration.tsx` | Configurable options |
> | `Service/addons.tsx` | Addons |
> | `Service/plan-change.tsx` | Upgrade or downgrade |
> | `Tickets/index.tsx` | Ticket list |
> | `Tickets/create.tsx` | New ticket |
> | `Tickets/show.tsx` | Ticket thread |

> [tab] Components
>
> In `{theme}/components/`. A component file replaces that piece everywhere, without copying any page. See [overriding components](#overriding-components).

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**

```bash theme={null}
mkdir -p resources/js/pages/themes/aurora/components
```

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.

```tsx resources/js/pages/themes/aurora/components/SectionCard.tsx theme={null}
export const SectionCard = ({ children, className = '' }: SectionCardProps) => (
    <div className={`bg-secondary border-primary rounded-3xl border-2 p-6 ${className}`}>
        {children}
    </div>
);
```

**3. Build and pick it**

Run the build, then choose Aurora under Settings, Appearance, Client Theme.

```bash theme={null}
npm run build
```

![The default theme sign in page](https://mintcdn.com/dezerx/W6tdUG_weSNDlVA2/public/themes/client-themes/before.webp?fit=max\&auto=format\&n=W6tdUG_weSNDlVA2\&q=85\&s=266894799adf86e18d0c0a31c1520320)

![The same page with the quanta theme](https://mintcdn.com/dezerx/W6tdUG_weSNDlVA2/public/themes/client-themes/after.webp?fit=max\&auto=format\&n=W6tdUG_weSNDlVA2\&q=85\&s=bf1af0e65824cba692406b39fb3da05f)

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.

> [!WARNING]
>
> 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.

```tsx theme={null}
export const SectionCard = ({ title, children }: SectionCardProps) => ( ... );
```

The export name matters. A `default` export also works.

> [!WARNING]
>
> Your component gets the same props as the original. Read the default one first, or you will drop loading states and permission checks.

> [accordion] Every overridable component
>
> Paths are relative to `{theme}/components/`.
>
> | Path | Export |
> | - | - |
> | `Button` | `Button` |
> | `Footer` | `Footer` |
> | `Modal` | `Modal` |
> | `Navbar` | `Navbar`, `ProfileDropdown` |
> | `Sidebar` | `Sidebar` |
> | `PageHeader` | `PageHeader` |
> | `SearchInput` | `SearchInput` |
> | `SectionCard` | `SectionCard` |
> | `StatusBadge` | `StatusBadge` |
> | `TabFilter` | `TabFilter` |
> | `EmptyState` | `EmptyState` |
> | `dashboard/banner-carousel` | `BannerCarousel` |
> | `dashboard/metrics-card` | `MetricsCards` |
> | `dashboard/notification` | `Notification`, `NotificationsContainer` |
> | `dashboard/payment-drawer` | `PaymentDrawer` |
> | `dashboard/payment-gateway-selector` | `PaymentGatewaySelector` |
> | `dashboard/services-table` | `ServicesTable` |
> | `dashboard/user-contact` | `UserContact` |
> | `checkout/BillingPaymentTab` | `BillingPaymentTab` |
> | `checkout/GuestAuthSection` | `GuestAuthSection` |
> | `checkout/OrderSummary` | `OrderSummary` |
> | `checkout/ServerConfigurationTab` | `ServerConfigurationTab` |
> | `checkout/TrustpilotBanner` | `TrustpilotBanner` |
> | `service/CancelModal` | `CancelModal` |
> | `service/DowngradeModal` | `DowngradeModal` |
> | `service/RenewModal` | `RenewModal` |
> | `service/UpgradeModal` | `UpgradeModal` |

> [accordion] Why the default theme ignores overrides
>
> 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.

> [!WARNING]
>
> 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](https://mintcdn.com/dezerx/W6tdUG_weSNDlVA2/public/themes/client-themes/colors.webp?fit=max\&auto=format\&n=W6tdUG_weSNDlVA2\&q=85\&s=0f6010e1b02a3602ab510972fbfc227f)

Use the existing classes and your theme follows light and dark mode, the Colors page and the corner setting for free.

```tsx theme={null}
<div className="bg-secondary border-primary rounded-xl border p-4">
    <h3 className="text-primary font-medium">Heading</h3>
    <p className="text-secondary text-sm">Supporting copy</p>
    <button className="button-primary rounded-lg px-4 py-2">Save</button>
</div>
```

![Settings, Appearance, Corners](https://mintcdn.com/dezerx/W6tdUG_weSNDlVA2/public/themes/client-themes/corners.webp?fit=max\&auto=format\&n=W6tdUG_weSNDlVA2\&q=85\&s=0c6e75f4b3e86d0fa79b29834c3e5e2a)

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.

> [accordion] The color variables
>
> ```css theme={null}
> --bg-primary        --text-primary       --border-primary
> --bg-secondary      --text-secondary     --border-secondary
> --bg-hover          --text-button        --border-third
> --bg-success        --text-success       --border-sidebar
> --bg-warning        --text-warning
> --bg-danger         --text-danger
> --bg-button-primary --bg-button-primary-solid
> --bg-button-secondary
> --icon-primary      --icon-text          --link-active
> --app-font-family
> ```
>
> Button helpers: `button-primary`, `button-secondary`, `button-success`, `button-warning`, `button-danger`.

> [accordion] Props and shared imports
>
> Theme pages are ordinary Inertia pages. Copy the default page you replace and keep its `PageProps`.
>
> ```tsx theme={null}
> const { props } = usePage();
> const user = props.auth?.user;
> const settings = props.auth?.settings;
> ```
>
> | Import | For |
> | - | - |
> | `@/contexts/LanguageContext` | `useTranslation()` |
> | `@/contexts/ToastContext` | `useToast()` |
> | `@/hooks/use-appearance` | Light and dark mode |
> | `@/lib/sanitize` | `createSanitizedSvg()` for SVG from settings |
> | `lucide-react` | Icons |
> | `framer-motion` | Animation |
>
> 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.

```bash theme={null}
npm run build
```

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`.

> [!TIP]
>
> 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`).

> [!WARNING]
>
> 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

| What you see | Cause |
| - | - |
| Theme missing from the list | Not directly under `themes/`, or not built yet |
| A page is ignored | The path does not match the page name, case included |
| A component override is ignored | Wrong path or export name, or the active theme is `default` |
| Sidebar and navbar vanished | A `layout` is set on a `UI/` page, remove it |
| Wrong in dark mode | Hardcoded colors instead of variables |
| Works in dev, not in production | Run the build |
| Gone after an update | Same name as a bundled theme, or Keep custom themes was off |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.