Simple ways to create a new theme in PrimeNG

This blog post is an excerpt from my upcoming book “Learning Angular UI Development with PrimeNG”.

We sometimes need to create our own themes instead of using the predefined ones. Web applications should often feature a company-specific look and feel, which is constant and preset by company-wide style guides. Creating new themes is easy with PrimeNG because it is powered by the ThemeRoller CSS Framework. ThemeRoller provides a powerful and easy-to-use online visual tool. In this blog post, we will systematically show all the required steps to create a new theme. There are two ways how to create a new theme — either by ThemeRoller or from scratch with Sass.

ThemeRoller approach

To gain first-hand experience of the ThemeRoller online visual tool, go to the ThemeRoller home page, explore the available theme’s Gallery, and play with the CSS properties to see changes for widgets embedded on the page. All CSS changes will be applied on the fly.

We have to select one of the existing themes (the Gallery tab) and edit it (the Roll Your Own tab). A click on the Download theme button accomplishes the work.

We should deselect the Toggle All Components option on the Download page so that our new theme only includes the skinning styles.

Next, we need to migrate the downloaded theme files from ThemeRoller to the PrimeNG theme infrastructure. The migration steps are straightforward.

1. The theme package that we have downloaded will have a CSS file jquery-ui.theme.css (as well as minified variant) and a folder images. Extract the package and rename the CSS file as theme.css.
2. In your web application, create a folder with the name of new theme, e.g. src/assets/themes/crazy.
3. Copy theme.css and the images folder into src/assets/themes/crazy.

After you are done with these steps, you can create a link to the theme.css in the index.html file.

This was the easiest way to create your custom themes without requiring knowledge of CSS.

Sass approach

The second way is more flexible and accurate. It is preferable to create a new theme manually by Sass because the theme is better maintainable. The main CSS settings, such as font, colors, border radius, etc., can be done configurable by Sass variables. You can create a new theme by setting custom values for those variables. This is exactly the approach followed by PrimeNG. The mostly free themes were created in such manner.

The free themes are hosted on GitHub at https://github.com/primefaces/primeng/tree/master/resources/themes.

Every theme has a separate folder with a Sass file where variables are set. The variables themselves are used in _theme.css — shared file for all free themes. This file can be found under node_modules/primeng/resources/themes/ if you install PrimeNG as dependency. Sometimes, you also need to set custom fonts or special settings for particular CSS selectors. You can overwrite default style rules with your own ones — just write them after importing _theme.css. The general structure of the custom theme file looks like as follows:

Let’s create the following folder structure with three Sass files for a new theme “crazy”:

Sass variables can be copied from any other theme, e.g. “omega”, and placed in _variables.scss. Some of them get custom values as shown below.

As you see, we would like to use a custom font “Quicksand”. You can download this font in .otf format (OpenType Font) from this free ressource: https://www.fontsquirrel.com/fonts/quicksand. For cross-browser support, we need fonts in four formats: .ttf, .eot, .woff and .svg. There are many converter tools, e.g. http://www.font2web.com, which allow to convert any .otf file to the mentioned four formats. After conversion, custom fonts should be moved to the fonts folder and installed via the @font-face rule.

Furthermore, we want to have pink gradient colors for widget’s header and red borders around invalid fields. All these custom rules are done in the theme file theme.scss. An excerpt from this file illustrates the idea.

The complete project with the theme “crazy” is available on GitHub at
https://github.com/ova2/angular-development-with-primeng/tree/master/chapter2/custom-theme

The proposed structure allows to create as many themes as you want. But how to compile theme.scss to theme.css? There are two ways to compile Sass to CSS.

1. Install the Sass from the command line. The installation process is described on the Sass homepage (http://sass-lang.com/install). Note that you need preinstalled Ruby. Once Sass is installed, you can runsass theme.scss theme.css from your terminal.
2. Use node-sass (https://github.com/sass/node-sass) under Node.js.

In the project on GitHub, we used node-sass along with autoprefixer (https://github.com/postcss/autoprefixer) and cssnano (http://cssnano.co). All required dependencies are installed locally.

Four handy NPM scripts in package.json help to create the theme file.

The path @import "primeng/resources/themes/theme" is found thanks to the option --include-path node_modules/ which sets the path to look for imported files. This helps to avoid all the mess with relative paths.

The command npm run build:css will produce theme.min.css which should be included on the page.

The look-and-feel of the new theme is amazing.