Onsen UI and PhoneGap – Getting Started4 min read

Onsen UI – The Answer to PhoneGap UI Development

Onsen UI – tutorial

Onsen UI – getting started

This is a getting started post on building an Onsen UI hybrid app. We will pick a simple template add a theme and then deploy the app to PhoneGap build to generate an installer.

The below screenshots are from my Samsung Galaxy Note I

Screenshots_2014-05-09-16-44-00Screenshots_2014-05-09-16-40-32Screenshots_2014-05-09-16-40-50You can download the installer from here. And if you want to submit this app to PhoneGap build, you can fork this repo.



To build a Hybrid app using PhoneGap & Onsen UI, you need to be aware of

Onsen UI

Onsen UI is

The Answer to PhoneGap UI Development

and is

A Custom Elements-Based HTML5 UI Framework

Some of its features include

Onsen UI is a front-end development framework for PhoneGap/Cordova hybrid apps. It focuses on the creation of usable mobile applications. Also, used with Monaca, it is simple to develop backend features and add device support.

Onsen UI is developed using Angular.js and Topcoat. Due to its robust architecture structure for mobile applications, you can take advantage of the powerful features of Angular.js.

Based on the Topcoat CSS framework, and adding CSS animation, OnsenUI can provide a native-like look & feel. Unlike other hybrid apps so far, it does not sacrifice the user experience in a mobile environment.

Since we got a basic idea on what Onsen UI is, let’s start the development.

Step 1 : Picking a Template & Running the app

To make building a boiler plate easy for us, Onsen UI folks have provide us with a few templates. You can find all the templates here.

We will pick the sliding menu & navigator template for this example. Click on the download button below the template & unzip the contents. Then open terminal/prompt inside the sliding_menu_navigator folder and run

node scripts/web-server.js

This will start a node server and host the app on it. Navigate to


to launch the home page. You can click on the links and buttons to open side navigation and pages.

Now, let’s change the theme. Open app/index.html in your favorite editor and look for

<link rel="stylesheet" href="lib/onsen/css/topcoat-mobile-onsen-ios7.css"> 

and replace it with one of the themes listed here. I liked the onsen-blue theme. So, pick the theme file path and replace the above line with

<link rel="stylesheet" type="text/css" href="lib/onsen/css/topcoat-mobile-onsen-blue.css">

Back to the browser and refresh the page and you will see the new theme showing up.

Simple and easy!

Step 2 : Scaffold a PhoneGap app

Let’s integrate our newly created Onsen app into PhoneGap. Create a new folder named myHybridApp. Open terminal/prompt here and run

phonegap create myOnsenUIApp

PS : If you face any issues, please refer the prerequisites. 

This will scaffold a new PhoneGap project for us and the folder structure should be

Screen Shot 2014-05-09 at 3.47.58 pm

Step 3 : Integrate Onsen UI with PhoneGap

Now, open myOnsenUIApp/www and delete the following

  • css folder
  • img folder
  • js folder
  • spec folder
  • index.html
  • spec.html

Do not delete the config.xml file. Then navigate to the unzipped template folder sliding_menu_navigator, where you have made the theme changes and copy all the contents of the app folder to myOnsenUIApp/www. 

The final folder structure should be

Screen Shot 2014-05-09 at 3.55.10 pmNext, open up www/index.html and add the below script tag

<script type="text/javascript" src="cordova.js"></script>


<script src="lib/onsen/js/angular/angular.js"></script> 

This is required for PhoneGap to work properly. cordova.js script will be a 404 if you open this page in a browser. No need to worry, when the build happens, PhoneGap will load this for us.

Next, we will update the PhoneGap app properties. Open www/config.xml. Update the name tag to OnsenUI PhoneGap App and description tag to something you like and also the author tag as you want. The name tag will be the name of your app when this code is processed through PhoneGap build.

Step 4 : Test the PhoneGap app

CD into myHybridApp/myOnsenUIApp folder and run

cordova platforms add ios


cordova platforms add android

This will create an iOS/android project inside the platforms folder. Next, build the app by running

cordova build ios  or cordova build android   or   cordova build

This will build the project. To run the project execute

cordova emulate ios  or   cordova emulate android

Note: For iOS you need to have latest xCode and ios-sim (sudo npm install -g ios-sim). And for Android, if you face issues, you can open the project using ADT. Refer prerequisites. 

And your output should be

iOS Simulator Screen shot 09-May-2014 4.14.25 pm   iOS Simulator Screen shot 09-May-2014 4.14.36 pm

iOS Simulator Screen shot 09-May-2014 4.14.41 pm   iOS Simulator Screen shot 09-May-2014 4.14.48 pm

Step 5 : Create a GitHub Repo & Commit

Navigate to GitHub and create a new repo named myOnsenUIApp. We will push only the www folder to the repo, since that is all we need to build the project.

Back to terminal/prompt and make sure you are CD-ed inside myHybridApp/myOnsenUIApp/www folder and run

git init 

to initialize a new repo

git add -A

to add all the files/folders inside www folder to local git repo

git commit -am "Initial Commit"

to create an initial commit

git remote add origin https://github.com/arvindr21/myOnsenUIApp.git

to map the local repo to the remote, replace the repo URL with  yours

git pull https://github.com/arvindr21/myOnsenUIApp.git

to sync the remote repo with local

git push origin master

to push the local changes to remote. You can go back to the GitHub repo in your browser and check if the files have properly updated.

That’s it. We are good to issue a PhoneGap build.

Step 6 : PhoneGap build the app

Navigate to   https://build.phonegap.com/apps   and click on + New App button. Then copy the git URL from the repo (https://github.com/arvindr21/myOnsenUIApp.git) to the “paste .git repo” textbox and you should see something like

Screen Shot 2014-05-09 at 4.47.19 pm

Click on Ready to Build button & you are good to go. After a few minutes, you will see the respective installers

Screen Shot 2014-05-09 at 4.50.10 pm

I don’t have the iOS developer key, so no iOS installer. But I have a Samsung Galaxy Note and I downloaded the apk and the navigation is smm..ooo..oth.

Yeoman Generator

Thanks to the request from Luke Warren, I have written a Yeoman Generator named generator-onsenui-phonegap that will scaffold an Onsen UI and Phonegap boilerplate for you.

To get started, create a new folder where you want to scaffold the application. Open terminal/prompt and run

Windows Mac/*nix
npm i -g yo grunt bower generator-onsenui-phonegap    sudo npm i -g yo grunt bower generator-onsenui-phonegap

Once this is done run

yo onsenui-phonegap

Yeoman will ask you to pick from the 7 available templates listed here. Once you have chosen, yeoman will scaffold the boilerplate code.

After scaffolding, to run the app in the browser, execute


and navigate to  http://localhost:1881.

Note: When you open the browser, you will find cordova.js as a 404 resource. This will be resolved, when you issue a PhoneGap build.

Once the development is done, you can submit the www folder to Phonegap build.

Next Steps

You can go through all the awesomely documents components here and try them out.

You can also go through the PhoneGap plugins and create your own apps. I have created a sample app using Contacts API and jQuery Mobile. You can try out the same with Onsen UI components.

Thanks for reading! Do comment.