Adding Custom Pages in WHMCS: Complete Guide

by | May 10, 2025 | Customization Tips

Learn how to add custom pages in WHMCS safely using template files, routes, and hooks. Perfect for terms pages, feature lists, or service info.

By default, WHMCS offers essential client and admin pages—but sometimes you need to add your own: a pricing table, FAQs, documentation, or custom service information. Thankfully, WHMCS allows you to create custom pages safely without altering core files.

In this guide, we’ll show you how to add a custom page in WHMCS (both frontend and admin area), and where to place files to keep them update-safe and organized.

Why Add Custom Pages in WHMCS?

  • Display service-specific information
  • Add legal pages (e.g., refund policy, terms of use)
  • Create feature comparison or pricing pages
  • Show knowledgebase-style content outside KB module
  • Build landing pages inside your billing system

1. Adding a Public Client Area Custom Page

Ideally, custom client area pages should be created through an Addon Module with proper client area integration.

However, if needed, you can also create a standalone page using the template below.

Step-by-Step Instructions:

<?php

use WHMCS\Authentication\CurrentUser;
use WHMCS\ClientArea;
use WHMCS\Database\Capsule;

define('CLIENTAREA', true);

require __DIR__ . '/init.php';

$ca = new ClientArea();

$ca->setPageTitle('Your Page Title Goes Here');

$ca->addToBreadCrumb('index.php', Lang::trans('globalsystemname'));
$ca->addToBreadCrumb('mypage.php', 'Your Custom Page Name');

$ca->initPage();

//$ca->requireLogin(); // Uncomment this line to require a login to access this page

// To assign variables to the template system use the following syntax.
// These can then be referenced using {$variablename} in the template.

//$ca->assign('variablename', $value);

$currentUser = new CurrentUser();
$authUser = $currentUser->user();

// Check login status
if ($authUser) {

    /**
     * User is logged in - put any code you like here
     *
     * Use the User model to access information about the authenticated User
     */

    $ca->assign('userFullname', $authUser->fullName);


    $selectedClient = $currentUser->client();
    if ($selectedClient) {

        /**
         * If the authenticated User has selected a Client Account to manage,
         * the model will be available - put any code you like here
         */

        $ca->assign(
            'clientInvoiceCount',
            $selectedClient->invoices()->count()
        );
    }

} else {

    // User is not logged in
    $ca->assign('userFullname', 'Guest');

}

/**
 * Set a context for sidebars
 *
 * @link http://docs.whmcs.com/Editing_Client_Area_Menus#Context
 */
//Menu::addContext();

/**
 * Setup the primary and secondary sidebars
 *
 * @link http://docs.whmcs.com/Editing_Client_Area_Menus#Context
 */
Menu::primarySidebar('announcementList');
Menu::secondarySidebar('announcementList');

# Define the template filename to be used without the .tpl extension

$ca->setTemplate('mypage');

$ca->output();

This example illustrates how to structure a custom page and includes:

  • How to initialize the page
  • Referencing language variables using Lang::trans
  • Authenticating the user and verifying a selected client account using CurrentUser
  • Assigning template variables with $ca->assign
  • Setting and rendering the desired template file

The template file should exist within your active WHMCS system theme folder. For the example provided, the path would be:
/templates/default/mypage.tpl

Once you’re ready to test:

  1. Upload the PHP file to the root directory of your WHMCS installation.
  2. Place the template file in your active template folder.
  3. Access the PHP file via your browser to view the page.

Note:
Custom pages created this way must be placed in the root WHMCS directory. Using this approach outside the root directory is not supported.

2. Add a Menu Link to the Custom Page

To add your custom page to the main navigation menu:

Add to: /includes/hooks/addcustomlink.php

use WHMCS\View\Menu\Item as MenuItem;

add_hook('ClientAreaPrimaryNavbar', 1, function(MenuItem $menu) {
    $menu->addChild('Custom Page')
         ->setUri('index.php?m=custompage')
         ->setOrder(50);
});

3. Creating Admin Area Pages (Optional)

Admin pages are more advanced and should only be created when needed using full WHMCS module structure. You’ll use controller files and admin/index.php routing.

Let me know if you need a guide for admin-side custom pages.

Best Practices

  • Never modify core files directly
  • Use your own addon module or hooks
  • Use the proper /templates/yourtheme/ folder for design
  • Organize files cleanly in a module structure
  • Use version control (like Git) to track changes

Conclusion

Adding custom pages in WHMCS is a great way to extend functionality, improve user experience, and tailor your client area to your business needs. Whether it’s a pricing table, FAQ, or special service info—now you can create it cleanly and safely.

Need help building WHMCS custom pages?
We offer development services for WHMCS modules, client area customizations, and design tweaks. Get in touch today for a custom quote.