WHMCS renders its entire client portal through Smarty, a templating engine that separates page logic from the actual HTML a customer sees, which is what makes a custom, fully branded theme possible without touching WHMCS’s own PHP code. The safe way to build one is a child theme: a small folder of overrides that sits on top of an existing system theme, Twenty-One or Nexus, rather than a full rewrite that has to be manually reapplied every time WHMCS ships an update.<\/p>\n\n\n\n
A child theme is not a shortcut around real customization work. It is a structure that keeps that work intact the next time WHMCS updates its default theme underneath you.<\/p>\n\n\n\n
WHMCS uses Smarty to control every page a customer sees in the client portal, from the login screen to an invoice to a support ticket thread. Smarty templates define the structure and content placement, WHMCS’s PHP code supplies the actual data, and the two come together at page load to produce the final HTML.<\/p>\n\n\n\n
Smarty is a general purpose PHP templating engine, not something WHMCS built itself, which means the syntax, variables wrapped in curly braces, conditional blocks, loops, follows Smarty’s own documented rules rather than a proprietary format unique to WHMCS. Anyone who has worked with Smarty on another PHP project already knows most of what they need here.<\/p>\n\n\n\n
WHMCS’s own developer documentation confirms this directly: WHMCS uses the Smarty templating engine specifically because it is fast and flexible enough to handle the range of dynamic, data driven pages a billing and client management system needs to generate.<\/p>\n\n\n\n
A System Theme is the overall visual and structural framework applied across the entire client portal, and WHMCS ships two by default: Twenty-One, introduced in WHMCS 8.1, and Nexus, introduced in WHMCS 9.0. An older theme called Six shipped with earlier WHMCS versions and is being phased out, so any new custom theme should build on Twenty-One or Nexus rather than Six.<\/p>\n\n\n\n
The active System Theme is set inside WHMCS at Configuration, System Settings, General Settings, under the General tab, and this same setting is where a custom or child theme gets selected once it exists.<\/p>\n\n\n\n
Every page in the client portal corresponds to one or more .tpl files, plain text files containing HTML mixed with Smarty syntax. A header.tpl and footer.tpl wrap around most pages, while individual pages like an invoice view or a support ticket list have their own dedicated template files defining that page’s specific layout.<\/p>\n\n\n\n
Variables inside these templates, written as a name wrapped in curly braces, get replaced with real data when WHMCS renders the page. A client’s name, an invoice total, a support ticket subject, all arrive in the template this way rather than being hard coded anywhere in the file itself.<\/p>\n\n\n\n
Smarty also supports conditional logic and loops directly inside the template file, an if block that only shows a renewal notice when a service is actually close to expiring, or a loop that lists every invoice a client has rather than a fixed number written by hand. This is what lets a single .tpl file correctly render a completely different result for a client with one active service versus a client with fifteen.<\/p>\n\n\n\n
Behind every .tpl file, WHMCS’s PHP code assembles the actual data, a client’s invoices, their active services, their ticket history, and hands it to Smarty as a set of named variables the template can then reference and display. The template itself never queries the database directly, it only receives and arranges what WHMCS’s PHP layer has already prepared.<\/p>\n\n\n\n
This same pattern extends beyond the client portal itself. WHMCS’s automated emails, invoices, welcome messages, renewal reminders, also render through Smarty, which is worth knowing if branded communication matters as much as the portal itself. Pairing consistently branded templates with reliable delivery through MailChannels<\/a> email infrastructure means a client’s entire experience, portal and inbox, stays visually and functionally consistent.<\/p>\n\n\n\n A safe custom WHMCS theme means building a child theme rather than editing a system theme directly: choosing a parent, creating a small folder of override files, and activating it, all without ever modifying the original Twenty-One or Nexus files WHMCS ships.<\/p>\n\n\n\n Twenty-One and Nexus are both valid parent themes, and WHMCS’s own documentation recommends building on one of these two rather than the older Six theme, which is on its way out of active support. For a brand new theme with no existing customization history to preserve, Nexus, being the newer of the two, is generally the more future proof starting point.<\/p>\n\n\n\n This decision applies regardless of which reseller tier a business runs WHMCS on, since the free WHMCS license<\/a> bundled with a SkyNetHosting reseller account includes the same theming capability across every plan, not a limited version on smaller tiers.<\/p>\n\n\n\n A child theme starts as a new folder inside the templates directory, named using only lowercase letters, numbers, hyphens, and underscores. Inside that folder, a theme.yaml file identifies it as a child theme and specifies which parent it builds on, using a config section with a parent value matching the parent theme’s directory name exactly, for example twenty-one.<\/p>\n\n\n\n That theme.yaml file can also declare a name, an author, and dependencies the theme relies on, but at minimum it needs the theme name and the parent directory reference to function as a valid child theme WHMCS recognizes.<\/p>\n\n\n\n This structure is a meaningful change from how WHMCS theming used to work in older versions, where a full custom theme required copying and maintaining an entire parent theme rather than just the pieces actually being changed. Anyone customizing WHMCS on version 8.0 or earlier is still working with that older, heavier approach, which is one more reason an update to a current version is worth prioritizing before investing significant time into a new theme.<\/p>\n\n\n\n A child theme does not need a copy of every file from its parent, only the specific files being customized. To change the footer, for example, only footer.tpl gets copied from the parent theme into the child theme’s own folder, where it can then be edited freely. Any file not copied into the child theme continues inheriting directly from the parent, which is exactly what keeps a child theme lightweight and easy to maintain.<\/p>\n\n\n\n CSS changes follow a similar, even simpler pattern: creating a css\/custom.css file inside the child theme folder is enough to layer custom styling on top of the parent theme without touching any of its original stylesheets directly.<\/p>\n\n\n\n Once the child theme folder and its theme.yaml file exist, it appears automatically in the System Theme dropdown at Configuration, System Settings, General Settings, alongside the default Twenty-One and Nexus options. Selecting it there activates it immediately for every client visiting the portal from that point forward.<\/p>\n\n\n\n WHMCS also checks for compatibility issues between the selected theme and any order form templates in use, and will surface a warning if something does not line up, which is worth resolving before considering the activation fully complete.<\/p>\n\n\n\n Customizing the client portal through Smarty means editing the specific .tpl files that control each visual element, the header, the footer, navigation, page layouts, while adding CSS and JavaScript through the child theme’s own asset files rather than touching anything belonging to the parent theme.<\/p>\n\n\n\n Copying header.tpl and footer.tpl from the parent theme into the child theme gives full control over the top and bottom of every client portal page, including the logo placement, top navigation links, and footer content like copyright text or support contact details.<\/p>\n\n\n\n Navigation structure and any sidebar content typically live in their own include templates, shared across multiple pages rather than duplicated on each one. Editing these shared includes, rather than individual page templates, is what keeps navigation changes consistent across the entire portal instead of applying inconsistently page by page.<\/p>\n\n\n\n This shared structure is also why a small navigation change, adding one new menu item, renaming a label, only needs a single file edited rather than the same change repeated across every page template individually. Finding the correct include file the first time saves considerably more effort than it costs.<\/p>\n\n\n\n Beyond the shared header, footer, and navigation, individual pages, the invoice view, the service details page, the support ticket list, each have their own template file controlling that page’s specific layout. These get copied into the child theme the same way header.tpl and footer.tpl do, only when a specific page actually needs a layout change.<\/p>\n\n\n\n A child theme’s css\/custom.css file is the standard place for style overrides, loaded after the parent theme’s own stylesheets so custom rules take precedence without needing to edit anything in the parent theme directly. Custom JavaScript follows a similar pattern, added as its own file and referenced from the child theme’s template files rather than injected into parent theme files.<\/p>\n\n\n\n Keeping these assets lean matters beyond just organization. A client portal loaded with unnecessarily heavy custom CSS or JavaScript is a page speed problem as much as a maintenance one, and hosting the WHMCS installation itself on faster infrastructure, such as NVMe backed VPS storage<\/a>, only partially compensates for assets that were never optimized in the first place.<\/p>\n\n\n\n Every copied template file arrives already using WHMCS’s own variables and include statements, and preserving those, rather than stripping them out during a redesign, is what keeps the page still functioning correctly after customization. A variable displaying a client’s name or an invoice total is doing real work, not decoration that can be safely deleted.<\/p>\n\n\n\n WHMCS specifically recommends maintaining the template includes and output variables present in the default header and footer when creating custom versions, since addons and third party extensions often rely on those same includes being present to display their own content correctly inside the portal.<\/p>\n\n\n\n Matching your brand inside WHMCS means applying your logo and colors consistently, structuring navigation the way your own website already does, and treating the client portal as a continuation of your brand rather than a separate, generic looking system a client happens to land on after checkout.<\/p>\n\n\n\n The Twenty-One, Nexus, and Six themes all display either a company name or an uploaded logo in the top left corner of the client portal, controlled through the $assetLogoPath variable. Uploading a logo through the Setup Wizard or at Configuration, System Settings, General Settings, saves it as logo.png or logo.jpg inside the assets image directory, where the theme picks it up automatically.<\/p>\n\n\n\n For a reseller already using MyCompanyWeb<\/a> storefront templates for the customer facing side of the business, matching that same logo and color treatment inside the WHMCS client portal closes what would otherwise be a visible seam between the storefront and the account management experience a client sees immediately after checkout.<\/p>\n\n\n\n The child theme’s css\/custom.css file is where brand colors, fonts, and spacing get applied across the portal, overriding the parent theme’s defaults without needing to hunt through every individual template file to change a color value repeated dozens of times.<\/p>\n\n\n\n Pulling actual values, hex codes, font names, spacing measurements, directly from an existing brand style guide or the main marketing website’s own stylesheet, rather than eyeballing a close match, is what makes the portal feel genuinely unified rather than merely similar in a general sense.<\/p>\n\n\n\n Navigation structure inside the client portal should mirror the logic a client already expects from your main website, grouping billing, support, and account settings the same way a client would intuitively look for them, rather than following WHMCS’s default arrangement purely because it shipped that way.<\/p>\n\n\n\nHow Can You Create a Safe Custom WHMCS Theme?<\/h2>\n\n\n\n
Choosing a suitable parent theme<\/h3>\n\n\n\n
Creating a child theme instead of modifying the default theme<\/h3>\n\n\n\n
Copying the required template files<\/h3>\n\n\n\n
Activating the custom theme in WHMCS<\/h3>\n\n\n\n
How Can You Customize the WHMCS Client Portal With Smarty Templates?<\/h2>\n\n\n\n
Customizing the header and footer<\/h2>\n\n\n\n
Changing navigation and sidebar presentation<\/h3>\n\n\n\n
Modifying page layouts and content sections<\/h3>\n\n\n\n
Adding your own CSS and JavaScript<\/h3>\n\n\n\n
Working with existing WHMCS template variables<\/h3>\n\n\n\n
How Can You Make Your WHMCS Client Portal Match Your Brand?<\/h2>\n\n\n\n
Applying your company logo and visual identity<\/h3>\n\n\n\n
Matching colors, typography, and spacing<\/h3>\n\n\n\n
Creating consistent navigation and customer journeys<\/h3>\n\n\n\n