Customizing Onsen UI Themes: Beginner’s Guide

Onsen UI comes with several themes to adjust the UI look for various types of apps. We are going to learn how to customize Onsen UI themes in this blog entry.

Installing and Building a Theme

Onsen UI themes are stored within the Onsen UI repository. First, clone the Onsen UI repository in a terminal window.

$ git clone https://github.com/OnsenUI/OnsenUI.git onsen

After cloning, execute the npm install command to resolve dependencies.

$ cd onsen 
$ npm install

The theme file is located within the themes directory. Gluntfile, used to build themes, is also under the themes directory.

Execute the grunt serve task within the themes directory. Then, the development environment will be ready to create Onsen UI themes.

$ cd themes 
$ grunt serve

Now, open http://0.0.0.0:9999/themes/testcases/ from the browser. You will be able to see the theme’s test cases created by topdoc.

Directory Structure

The following is the directory structure under the theme directory:

.
├── css
├── img
├── testcases
│   ├── css
│   └── js
├── testcases-topdoc-template
│   ├── css
│   └── js
└── theme-modules
    ├── android4_4
    ├── common
    ├── ios7
    └── onsen

There are two import directories here: the css directory and the theme-module directory.

• css: Generates the theme’s CSS files.
• theme-modules: Stores each theme’s stylus files.

You can customize a theme by editing the stylus file within theme-modules.

Customizing a Theme

The Onsen UI’s theme CSS is written in stylus, a CSS meta-language.

Before you start editing the stylus file within the theme-modules directory, make sure that the grunt serve task is running within the themes directory. This task automatically compiles to CSS when the stylus file within the theme-modules is updated.

$ grunt serve

Now, let’s try changing the iOS7 theme color. Open the theme-modules/ios7/variables-onsen-ios7.style file, and replace line 9 with the below:

var-theme-ios7-blue = #ff3b30

Once the change has been made to the stylus file, the theme will be automatically compiled. Open http://0.0.0.0:9999/themes/testcases/ from the browser. When successful, you should be able to see the theme color has changed as below:

You can change other parts of the theme with these same steps. The compiled theme’s CSS file is generated within the themes/css directory.

Closing Notes

Not only does Onsen UI offer various themes to choose from, but also the freedom to expand or customize them to create a specific and original look for your app. I hope you enjoyed learning how to customize Onsen UI themes. Thanks for reading!

Originally published at onsen.io on March 27, 2014.