--- title: "Payload Per-Tenant Theming: Ultimate Admin Styling" slug: "payload-per-tenant-theming-admin" published: "2026-08-01" updated: "2026-08-10" validated: "2026-08-10" categories: - "Payload" tags: - "Payload per-tenant theming" - "@payloadcms/plugin-multi-tenant" - "useTenantSelection" - "data-tenant attribute" - "Payload admin theming" - "TenantThemeSync" - "tenant theme map" - "color-mix CSS" - "accent-color" - "Payload Next.js" - "admin CSS override" llm-intent: "reference" audience-level: "intermediate" framework-versions: - "@payloadcms/plugin-multi-tenant@latest" - "payload@latest" - "next.js@15" - "react@18" - "typescript@5" - "scss@latest" status: "stable" llm-purpose: "Payload per-tenant theming: step-by-step guide to use @payloadcms/plugin-multi-tenant and useTenantSelection to add scoped admin CSS. Implement the…" llm-prereqs: - "Access to @payloadcms/plugin-multi-tenant" - "Access to Payload CMS" - "Access to Next.js" - "Access to React" - "Access to TypeScript" llm-outputs: - "Completed outcome: Payload per-tenant theming: step-by-step guide to use @payloadcms/plugin-multi-tenant and useTenantSelection to add scoped admin CSS. Implement the…" --- **Summary Triples** - (sourceOfTruth, is, useTenantSelection() from @payloadcms/plugin-multi-tenant) - (tenantSyncComponent, writes, selected tenant id to data-tenant attribute on (or )) - (stylesheet, keysOff, the data-tenant attribute to scope admin CSS per tenant) - (implementation, avoids, URL parsing, cookies, or duplicate tenant-selection mechanisms) - (fallbackBehavior, preserves, stock Payload look when no tenant is selected or tenant id is unknown) - (themeValues, shouldBeMapped, tenant id → CSS custom properties (e.g., --accent)) - (visualEffects, canUse, color-mix() and accent-color to create subtle background tints and brand accents) - (adminUI, isNotModified, navigation, forms or collection views beyond styling) ### {GOAL} Payload per-tenant theming: step-by-step guide to use @payloadcms/plugin-multi-tenant and useTenantSelection to add scoped admin CSS. Implement the… ### {PREREQS} - Access to @payloadcms/plugin-multi-tenant - Access to Payload CMS - Access to Next.js - Access to React - Access to TypeScript ### {STEPS} 1. Read tenant selection with hook 2. Create tenant-to-theme mapping 3. Sync selection to DOM attribute 4. Load custom admin stylesheet 5. Scope CSS to theme variables 6. Test fallbacks and edge cases # Payload Per-Tenant Theming: Ultimate Admin Styling > Payload per-tenant theming: step-by-step guide to use @payloadcms/plugin-multi-tenant and useTenantSelection to add scoped admin CSS. Implement the… Matija Žiberna · 2026-08-01 Making the Payload Admin UI react visually to whichever tenant is selected comes down to reading tenant state from `useTenantSelection()`, mirroring that value onto a `data-tenant` attribute on ``, and letting a custom stylesheet key off that attribute. No second tenant-selection mechanism, no URL parsing, no extra cookie. This guide walks through the full setup: a subtle background tint, a brand accent color, and the fallback behavior that keeps unselected or unknown tenants looking like stock Payload. I built this for a multi-brand client project running several tenants through `@payloadcms/plugin-multi-tenant`, where each brand needed its own accent color in the Admin panel without touching Payload's navigation, forms, or collection views. The pattern below is what shipped, including the edge cases that came up during testing. ## The Data Flow Before the code, it helps to see the whole chain in one place: ``` Payload's tenant selector (@payloadcms/plugin-multi-tenant) ↓ useTenantSelection() ← the only source of truth, official client API ↓ a small "sync" client component ↓ sets an attribute on (or ) ↓ a custom stylesheet keys off that attribute ``` Every step below maps to one link in that chain. ## 1. Read Tenant Selection from the Official API `@payloadcms/plugin-multi-tenant` already exposes a client hook for this. Reach for it directly instead of building a parallel tenant-tracking mechanism: ```ts // File: use-tenant-theme-key.ts import { useTenantSelection } from "@payloadcms/plugin-multi-tenant/client"; const { selectedTenantID, options } = useTenantSelection(); ``` `selectedTenantID` is the id of the currently selected tenant, or `undefined` if none is selected. `options` is an array of `{ label, value }` pairs, where `value` is the tenant's id and `label` comes from whatever field the tenant collection's `admin.useAsTitle` is set to, typically `name`. One limitation worth knowing up front: `options` only exposes `useAsTitle` and `id`. It doesn't include a tenant's `slug` or any other field. If you need a stable, CSS-safe key and your `useAsTitle` value isn't one, keep a small lookup table mapping label to key, covered in the next step, rather than fetching extra tenant data over the network on every switch. A few things to skip entirely here. Don't read the tenant from the URL unless your app's routing already does that for other reasons. Don't add a second cookie or localStorage preference. Don't build a second `