Development Guides Home >> Guide to cPanel Interface Customization and Branding >> Guide to cPanel Interface Customization - Style Development

Guide to cPanel Interface Customization - Troubleshoot Custom Styles



Custom styles are only available in the Paper Lantern theme. The Paper Lantern theme is now deprecated and will be removed. For more information, read our cPanel Deprecation Plan documentation.

Use this document to troubleshoot your custom styles.

We strongly recommend that you keep your custom styles up to date to avoid compatibility issues when you upgrade cPanel & WHM. To do this, perform the following actions:

  • Monitor our Change Logs and our Release Notes documentation for updated features and bug fixes.
  • Make certain that your server runs on the LTS, STABLE, RELEASE, or CURRENT release tiers , so that it receives any functionality updates.
  • You can also use a server that runs on the EDGE release tier to test for compatibility and functionality in a controlled environment.

Custom CSS does not render

Problem: The cPanel interface does not render some or all of the custom CSS elements that you added to the styles.css file.

Solution: In most cases, this problem occurs because the styles.css file does not exist in the correct location. Make certain that you saved your styles.css file in the appropriate location:

  • For all of the accounts on the server – /var/cpanel/customizations/styled/mystyle/
  • For all of the cPanel accounts that a reseller owns – /home/reseller/var/cpanel/reseller/styled/mystyle/
  • For a specific cPanel account – /home/username/var/cpanel/styled/mystyle/
    • mystyle represents the name of the style's directory.
    • reseller represents the reseller's username.
    • username represents the cPanel account's username.
    • If the server uses a customized home directory path, make certain that you use the appropriate path for that home directory.
    • If these directories do not currently exist on the server, use the mkdir command to create them.

If the styles.css file exists in the correct location, perform the following steps to check whether the cPanel interface uses custom CSS files correctly:

  1. Create a new style directory within the appropriate directory.
  2. In your preferred text editor, create a styles.css file in the new directory with the following contents:
    body {
        background-color: blue;
  3. Use your preferred method to apply the style that you just created. To make certain that you applied the style correctly, we recommend that you apply the style through the cPanel interface.
  4. Navigate to the cPanel interface in your browser, and perform a hard refresh.
    • On MacOS® computers, press Command+Shift+R .
    • On Windows® computers, press Ctrl+F5 .
  5. Check whether the cPanel interface now displays a blue background. If it does, the styles.css file exists in the correct location, and the cPanel interface can read it correctly.
  6. Check your CSS file for errors. If the problem persists and no errors exist in the file, you may need to submit a ticket with cPanel Technical Support .

Custom icons do not display

Problem: Your custom style includes custom icons, but the cPanel interface continues to display the default cPanel-provided icons, or icons from another style.

Solution: In most cases, this problem occurs because you did not run the /usr/local/cpanel/bin/sprite_generator utility after you applied the style. This utility integrates your icons into the cPanel interface's icon set.

To use this utility, run the following command, where mystyle represents the style name:

/usr/local/cpanel/bin/sprite_generator --theme paper_lantern --style mystyle

If this command does not solve the issue, confirm that you stored the icons in the correct location in your style, and that they use the correct filenames.

  • You must save icon files in the icons subdirectory within the main style directory. For example, if you created the mystyle style and applied it to all of the accounts on the server, icon files should exist in the /var/cpanel/customizations/styled/mystyle/icons/ directory.
  • To replace existing cPanel feature icons, you must use the same names and file extensions as the icons that you wish to replace.
    • For example, to replace the File Manager feature's png icon, you must save the icon as the file_manager.png file. Or, to replace the svg format icon, save the icon as the file_manager.svg file.
    • For more information, read our Guide to cPanel Interface Customization - Appkeys documentation.

You must clear your browser's cache regularly while you troubleshoot this issue. If your browser caches the cPanel interface, you may not see the results of your changes immediately.