Development Guides Home >> Quickstart Development Guide

Tutorial - Create a Custom cPanel Style

Introduction

This tutorial creates a custom cPanel style for the Paper Lantern theme and applies it to the cPanel or Webmail interfaces. Styles are only available in the Paper Lantern theme. For customization in the Jupiter theme, read our Guide to cPanel Customization and Branding in the Jupiter Theme documentation.

For the purposes of cPanel, L.L.C.'s products and documentation, we use the following terms:

• Branding  — Branding modifies the cPanel interface in order to match your company's logo and brand. 
  • Branding changes include updates to image assets or text labels.
  • For more information, read our  Branding  documentation.
• Includes  — UI includes add custom content to the header or footer of the cPanel interface (but not the WHM interface). 
  • You can create UI includes for specific cPanel interfaces, or global UI includes that display on all of cPanel's interfaces. 
  • For more information, read our  UI Includes  documentation.
• Plugin  — A plugin modifies an interface's features or functionality, and it may also include changes to the interface's appearance.
  • You can write plugins for the cPanel or WHM interfaces.
  • You can use the  cPanel Style Guide  to ensure that your interfaces match the appearance of standard cPanel interfaces.
  • For more information, read our  Guide to cPanel Plugins in the Paper Lantern Theme  documentation.
• Style  — A style uses CSS, images, and other assets to modify the appearance of the entire cPanel interface  without  changes to its functionality or features. 
  • You can create and apply styles to an entire server or a specific reseller's accounts, or you can create them for distribution. 
  • For more information, read our  cPanel Style Development  documentation.
• Theme  — A theme applies an overlay on the skeletal framework for all of the interfaces.
  • cPanel & WHM currently ships with one default cPanel theme and one default WHM theme.
  • The Webmail and login interfaces also use themes.

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.

You can download an example skeleton style to help you create a new style.

Create a custom cPanel style

Create a new directory for the new style.

Create the directory that will contain your style's styles.css file and its images and other assets.

To create a directory from the command line, run the following command, where mystyle represents your style's name:

mkdir mystyle

Create the styles.css file.

Create the styles.css file within the directory that you just created. Use your preferred text editor to add the desired CSS code to the file.

• For examples of CSS elements that you can add, read our  Guide to cPanel Style Development - The styles.css File  documentation.
• cPanel styles use Twitter Bootstrap elements. For more information, read the  Twitter Bootstrap  documentation.

Add custom icons.

You can replace the cPanel interface's default icons with custom icons for your style.

To replace the default cPanel icons with your own icons, perform the following steps:

1. In your style's directory , create the  icons  subdirectory.
2. Save your icons with the same name and file extension as the feature icons that you wish to replace. 
   • For example, to replace the  File Manager  icon, save a  .png  version of the icon as the  file_manager.png  file (cPanel & WHM version 58 and earlier) or an  .svg  version of the icon as the  file_manager.svg  file (cPanel & WHM version 60 and later).
   • For a full list of feature icon names, read our  Guide to cPanel Interface Customization - Appkeys  documentation.

For additional information about icon requirements, read our Guide to cPanel Interface Customization - Custom Icons and Logos documentation. 

Add a preview image.

To add a preview image to your custom style, save the image as the preview.png file within the style's directory.

• cPanel's  Change Style  interface ( cPanel >> Home >> Preferences >> Change Style ) and WHM's Customization  interface ( WHM >> Home >> cPanel >> Customization ) will display this image with the options for the style.
• We recommend that you use a  500  by  500  pixel image as the preview image.

Move the style directory to the appropriate location on the server.

Use the mv command to move your style's directory to the appropriate location on the server:

• 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/

Apply the style.

Use the appropriate method to apply the style to one or more cPanel accounts on the server:

To apply a style as the server's default style, perform the following steps:

1. Log in to the server via SSH as the  root  user. 
2. Create the  /var/cpanel/customizations/styled  directory, if it does not already exist.
3. Run the following command, where  path_to_style  represents the absolute path to the style that you wish to apply:

ln -s path_to_style /var/cpanel/customizations/styled/default_style

For example, to apply the /var/cpanel/customizations/styled/mystyle style, run the following command:

ln -s /var/cpanel/customizations/styled/mystyle /var/cpanel/customizations/styled/default_style

To apply a style to all of a reseller's accounts as the default style, perform the following steps:

1. Log in to cPanel as the reseller. 
2. Navigate to cPanel's Change Style  interface ( cPanel >> Home >> Preferences >> Change Style ).
3. Click  Set as Default  for the desired style.

To apply a style to a specific account through the cPanel interface, perform the following steps:

1. Log in to cPanel as the desired user. 
2. Navigate to cPanel's  [ Change Style ] (( https://docs.cpanel.net/cpanel/preferences/change-style/ ) interface ( cPanel >> Home >> Preferences >> Change Style ).
3. Click  Apply  for the desired style.

To apply a style to a specific account through the command line, perform the following steps:

1. Log in to the server via SSH as the desired user. 
2. Run the following command, where  username  represents the cPanel account's username, and  path_to_style  represents the absolute path to the style that you wish to apply:

   ln -s path_to_style /home/username/var/cpanel/styled/current_style

   For example, to apply the /var/cpanel/customizations/styled/mystyle style for the username user, run the following command:

       ln -s /var/cpanel/customizations/styled/mystyle /home/username/var/cpanel/styled/current_style

If the style includes custom icons, run the sprite_generator utility.

After you apply a style that uses custom icons, run the following command, where mystyle represents the style name:

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

The /usr/local/cpanel/bin/sprite_generator utility integrates your icons into the new icon set.

Troubleshoot custom styles.

If you experience problems after you apply a custom style, read our Troubleshoot Custom Styles documentation.