Tutorial: Customizing Onsen UI Themes

Onsen UI has a wide set of premade themes, which cover a rich set of color combinations. Although the default colors look good, when creating an app with Onsen UI we recommend customizing the theme to give the app a personal touch. Branding is important since it differentiates your app from others and makes it easily recognizable.

How can the developer modify these themes, to give the Onsen UI components the desired colors? There are two ways to accomplish this.

The first one is to use our Theme Roller Tool, which provides, thanks to an intuitive graphical interface, an easy way to customize Onsen UI themes.

The second way to customize themes is by modifying and compiling the Stylus files. Using an automated gulp task and live reloading this approach also powerful and easier to integrate into a normal developer workflow.

Why should I modify themes manually?

If you have already took a look at this tutorial, you probably noticed that the Onsen UI Theme Roller Tool not only allows you to customize themes, but also provides the functionality to export them, making your new themes ready to be imported into the app’s project. This approach has some limitations: the theme will be limited to the current version of Onsen UI. In case of future structure changes, it could not be compatible anymore with the new framework releases.

The dynamic customization of the themes is the solution of this kind of problems. Onsen UI themes are codified as Stylus, providing an efficient, dynamic, and expressive way to generate CSS.

Using the .styl file extension, Stylus accepts the standard CSS syntax, but it also accepts some other variations where brackets, colons, and semi-colons are all optional.

Let’s see how to modify the Stylus themes and how to verify the changes in real time.

Prerequisites

If you already have gulp installed you can skip this.

You will need Node.js in this tutorial. Please download it from the official website. After Node.js is installed you will have access to a program called npm which is a package manager for Node.js, it allows you to easily install Node.js modules.

We now need to install gulp, which is a task runner for Node.js. In a terminal run the following command:

$ sudo npm install -g gulp

If you’re on Windows you can omit the “sudo”. This will install gulp globally so you have access to it everywhere.

Let’s start!

First of all, download one of the Onsen UI templates at this page (any template is fine), extract it and navigate to the root folder.

We now need to install some dependencies, so we run:

$ npm install

After that is done we can start serving the project:

$ gulp serve

This starts a web server and the output should look something like this:

Normally a browser will open automatically but if it doesn’t (or you accidentally close it) you can find the URL in the output.

Now open www/index.html in a text editor. We can see what theme is currently used near the top of the file:

<link rel="stylesheet" href="styles/onsen-css-components-blue-basic-theme.css">

This corresponds to the colors defined in www/lib/onsen/stylus/blue-basic-theme.styl. The content of that file will be something like this:

As you can see it contains are the colors for the Onsen UI components. By customizing this file you can add personality to your app.

Try changing the color of the toolbar by changing the $toolbar-background-color variable. When you save the file the Stylus files will be instantly compiled and the browser reloaded so you can see the changes instantly.

Keep customizing the variables until you’re satisfied with how your app looks. The colors is just one part of making a successful app but I think most people would agree when I say that it’s darn important!

Conclusion

Have you seen how easy is to modify an Onsen UI theme? Why don’t you try and share your results with us?! If you have any trouble getting started please ask in the comments and we will do our best to help you.

Continue to follow our Blog and take a look at our GitHub page (in case you like it, give us a star, please!). In case you have comments or advice, please let us know. Your opinion matters!


Originally published at onsen.io on April 23, 2015.