{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Navigation","description":"Developer documentation for the WHMCS API — the","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"navigation","__idx":0},"children":["Navigation"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"navigation-bars","__idx":1},"children":["Navigation Bars"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Tip"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide assumes you are already familiar with creating and using ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/hooks/"},"children":["Hook files in WHMCS"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are two navigation bars in WHMCS's client area. They exist as part of the system theme."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The primary navigation bar contains the bulk of the menu and floats to the left of the secondary navigation bar. The secondary navigation bar contains user-specific items and changes if a client is logged in to WHMCS. When a client is not logged in then the secondary navigation contains a login link, and when a client is logged in then the secondary menu contains links to the client's account."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Responsive mode is activated when WHMCS's client area is viewed on a smaller screen device such as a phone or tablet. At that point, WHMCS will collapse the navigation bar into a fold-out menu."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The navigation bar elements are controlled in a programmatically, allowing modules and hooks to dynamically interact with the navigation menu elements."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The look and feel of the navigation bar can be customised via the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/header.tpl"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/includes/navbar.tpl"]}," system theme template files."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"finding-a-menu-name","__idx":2},"children":["Finding a Menu Name"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every menu item has a unique name that is used to reference it. You will need this name in order to manipulate it. To make it easier, we have made the name of each sidebar menu item available in the HTML source of the page, which means it can be retrieved using the ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Inspect Element"]}," option available in most modern browsers. For example:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/menus-find-name.d63ba8a1dc95a68d277c815af652a6bbb0334053eb90d4a7692a12cf8ecbef18.008c120b.png","alt":"Navigation Menus: Finding a Menu Name"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once you have the menu item name that you wish to manipulate, which in the example above is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Account Details"]},", you can manipulate it as described below."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Tip"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The client area's menu system is defined in a tree structure. Each menu item has one parent item and can have many child items. To manipulate a menu item within a sidebar panel, you first need to retrieve the parent menu item, which in the case above is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Account"]},", followed by the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Account Details"]}," menu item within it."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"changing-the-text-label-of-a-menu-item","__idx":3},"children":["Changing the Text Label of a Menu Item"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All sidebar menu items that are supplied by default use display names controlled by language files. Simply search in your active language file for the text you see in the menu item label, and you can adjust or change it there as required."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Alternatively, you can manipulate the display text via a hook as follows:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"<?php\n\nuse WHMCS\\View\\Menu\\Item as MenuItem;\n\nadd_hook('ClientAreaPrimarySidebar', 1, function(MenuItem $primarySidebar)\n{\n    $primarySidebar->getChild(\"My Account\")\n        ->getChild(\"Billing Information\")\n        ->setLabel(\"Custom Text Here\");\n});\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The above example retrieves the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["My Account"]}," menu item, followed by the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Billing Information"]}," menu item, which is a child within that. The same logic should be applied to all dropdown menu items."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"changing-where-a-menu-item-links-to","__idx":4},"children":["Changing where a Menu Item Links To"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can change where a menu item points using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["setUri"]}," method. For example, if you use an external system to control announcements, you could do something like the following:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"<?php\n\nuse WHMCS\\View\\Menu\\Item as MenuItem;\n\nadd_hook('ClientAreaPrimaryNavbar', 1, function (MenuItem $primaryNavbar)\n{\n    $navItem = $primaryNavbar->getChild('Support');\n    if (is_null($navItem)) {\n        return;\n    }\n\n    $navItem = $navItem->getChild('Announcements');\n    if (is_null($navItem)) {\n        return;\n    }\n\n    $navItem->setUri('https://www.example.com/3rdpartyblogsystem');\n\n});\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"rearranging-menu-items","__idx":5},"children":["Rearranging Menu Items"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can change the display order of menu items as follows:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"<?php\n\nuse WHMCS\\View\\Menu\\Item as MenuItem;\n\nadd_hook('ClientAreaPrimaryNavbar', 1, function (MenuItem $primaryNavbar)\n{\n    $navItem = $primaryNavbar->getChild('Support');\n    if (is_null($navItem)) {\n        return;\n    }\n\n    $navItem = $navItem->getChild('Announcements');\n    if (is_null($navItem)) {\n        return;\n    }\n\n    $navItem->setOrder(1);\n\n});\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following helpers are also available:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"// Moves a menu item up one position\n$primaryNavbar->getChild('Support')->getChild('Announcements')->moveUp();\n// Moves a menu item down one position\n$primaryNavbar->getChild('Support')->getChild('Announcements')->moveDown();\n// Moves a menu item to the first position\n$primaryNavbar->getChild('Support')->getChild('Announcements')->moveToFront();\n// Moves a menu item to the last position\n$primaryNavbar->getChild('Support')->getChild('Announcements')->moveToBack();\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"adding-a-menu-item","__idx":6},"children":["Adding a Menu Item"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can add a new link to the primary navigation as follows:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"<?php\n\nuse WHMCS\\View\\Menu\\Item as MenuItem;\n\nadd_hook('ClientAreaPrimaryNavbar', 1, function (MenuItem $primaryNavbar)\n{\n    $primaryNavbar->addChild('Menu Name')\n        ->setUri('https://www.example.com/')\n        ->setOrder(70);\n});\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"adding-an-additional-child-menu-item","__idx":7},"children":["Adding an Additional Child Menu Item"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can add additional menu items as follows:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"<?php\n\nuse WHMCS\\View\\Menu\\Item as MenuItem;\n\nadd_hook('ClientAreaPrimaryNavbar', 1, function (MenuItem $primaryNavbar)\n{\n    if (!is_null($primaryNavbar->getChild('Support'))) {\n        $primaryNavbar->getChild('Support')\n            ->addChild('Emergency Contacts', array(\n                'label' => Lang::trans('emergencyContacts'),\n                'uri' => 'emergency.php',\n                'order' => '100',\n            ));\n    }\n});\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To add a menu item conditionally based on client login status, you can do that using menu context as follows:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"<?php\n\nuse WHMCS\\View\\Menu\\Item as MenuItem;\n\nadd_hook('ClientAreaPrimaryNavbar', 1, function (MenuItem $primaryNavbar)\n{\n    $client = Menu::context('client');\n\n    // only add menu item when no client logged in\n    if (is_null($client)) {\n        $primaryNavbar->addChild('Example')\n            ->setUri('https://www.example.com/')\n            ->setOrder(100);\n    }\n});\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"hiding-or-removing-a-menu-item","__idx":8},"children":["Hiding or Removing a Menu Item"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can remove a menu item as follows:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"<?php\n\nuse WHMCS\\View\\Menu\\Item as MenuItem;\n\nadd_hook('ClientAreaPrimaryNavbar', 1, function (MenuItem $primaryNavbar)\n{\n    if (!is_null($primaryNavbar->getChild('Support'))) {\n        $primaryNavbar->getChild('Support')->removeChild('Announcements');\n    }\n});\n"},"children":[]}]},"headings":[{"value":"Navigation","id":"navigation","depth":1},{"value":"Navigation Bars","id":"navigation-bars","depth":2},{"value":"Finding a Menu Name","id":"finding-a-menu-name","depth":2},{"value":"Changing the Text Label of a Menu Item","id":"changing-the-text-label-of-a-menu-item","depth":2},{"value":"Changing where a Menu Item Links To","id":"changing-where-a-menu-item-links-to","depth":2},{"value":"Rearranging Menu Items","id":"rearranging-menu-items","depth":2},{"value":"Adding a Menu Item","id":"adding-a-menu-item","depth":2},{"value":"Adding an Additional Child Menu Item","id":"adding-an-additional-child-menu-item","depth":2},{"value":"Hiding or Removing a Menu Item","id":"hiding-or-removing-a-menu-item","depth":2}],"frontmatter":{"title":"Navigation","seo":{"title":"Navigation"}},"lastModified":"2026-08-03T17:00:42.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/themes/navigation","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}