WHMCS Theme Customization

Which parts of the WHMCS client area can be restyled?

Nearly every customer-facing screen can be restyled, because each one is rendered by a Smarty template file in the theme folder. The table lists the parts people ask about most.

How is a WHMCS theme built?

A WHMCS theme is a folder inside templates/ holding Smarty .tpl files plus the CSS, JavaScript and images they load. Order forms are separate templates under templates/orderforms/, so the cart and the client area can be styled independently.

Smarty is a PHP template language. A file mixes HTML with tags such as {$variable}, {if} and {foreach}, and WHMCS supplies the variables for each page. You pick the active theme in the admin general settings and an order form per product group. Because the logic is separate from the layout, I can move, hide or restyle a section without touching how WHMCS processes the data behind it. That is also why design changes rarely threaten billing.

Why do my changes go in a child theme and never in core files?

Changes go in a child or custom theme folder because a WHMCS upgrade overwrites the default theme's files, and any edit made to them disappears. A child folder is not touched by the upgrade.

A child theme holds only the files I have changed. For every other page, WHMCS falls back to the parent theme, which keeps the child small and easy to review. For the default Twenty-One theme, the child folder declares its parent in a small theme.yaml file. Where I can, I avoid editing templates at all. I use the ClientAreaHeadOutput and ClientAreaFooterOutput hooks to add CSS and JavaScript, and a file in lang/overrides/ to reword text. Each of those survives upgrades with no template copy to maintain. The trade-off is that a child theme still inherits parent updates, so I retest after each WHMCS release.

Can you customize a commercial theme I already own?

Yes, provided you hold a license for it and the vendor permits changes. I work within the vendor's own override method, which is usually a custom folder, a settings panel or a custom stylesheet.

I do not edit encoded vendor files, and I do not work on pirated copies of any theme. If a theme encodes parts of its code, I can only change what the vendor exposes. Before I start, I record the theme version and list the files I change, so a vendor update can be compared with my work instead of overwriting it blindly. If you do not own a theme yet, note that I am the founder of WHMCSPilot.com, which sells premium themes. You are under no obligation to buy from it, and custom work on the default theme is a legitimate alternative.

How do you check mobile, accessibility and speed?

I test every changed page at phone, tablet and desktop widths, with a keyboard and with a contrast checker, and I time how the page loads. Order forms get the most attention because a broken cart loses sales directly.

• Mobile: I test at narrow widths and on a real phone, including tapping the checkout buttons, filling the forms and paying.
• Accessibility: I check text and button contrast, visible focus outlines, form labels and a keyboard-only run through the order flow. I work toward WCAG AA guidelines, but I do not certify compliance.
• Speed: Smarty compiles each template once and stores the result in templates_c. The first view after a change is slower, and the folder must stay writable. I also keep heavy scripts and large images out of the page.

If the client area is slow but the theme is light, the cause is usually the server or the database, not the template. I check PHP and database settings before blaming the design, and the troubleshooting guide covers that kind of check.

How do email templates and PDF invoices fit in?

Email templates are edited in the WHMCS admin area, while PDF invoices use a separate layout. Both should carry the same brand as the client area so customers see one consistent company.

Email templates use Smarty merge fields such as the client name and invoice number. I restyle the shared header and footer, then open every changed template with test data to catch broken fields. I also check the plain-text version and the look in the major mail clients. For the PDF invoice, I use the override method your WHMCS release supports instead of editing core files. I match logo size, company details and tax lines, then test long item names, several currencies and right-to-left or non-Latin text, since the PDF engine needs fonts that contain the characters.

What is outside theme work?

I will not edit WHMCS core files or default theme files, install pirated themes, or promise a particular conversion rate or search ranking from a design change. I do not certify accessibility compliance, and I do not design brand identities from scratch. Theme work also stops at the template layer. If a feature needs new behavior, such as an extra page backed by its own data, that becomes a custom module and is quoted separately. For a fresh system that needs both configuration and styling, see WHMCS development.