Getting Started

The official guide assumes basic level knowledge of HTML, CSS, and JavaScript. If you are totally new to JavaScript development, it might be the best to grasp the basics then come back and reading through the guide.

What is Onsen UI?

Onsen UI is…

A large set of rich UI components specifically designed for mobile apps

specifically designed for mobile apps Packed with ready-to-implement features following native iOS and Android design standards

Free to use, 100% open source software (Apache v2 license)

Onsen UI enriches app users’ mobile experience with natively designed UI elements. It’s perfect for developing hybrid apps using Cordova or developing mobile web apps (also referred to as Progressive Web Apps). For more information on these types of implementation, see Deploy to PWA & Cordova.

Future-Proof Architecture

Under the hood, Onsen UI consists of three layers:

CSS Components, written in cssnext, the next generation of CSS Web Components, written in native JavaScript to support ALL frameworks Framework Bindings, created for tighter integration with popular frameworks such as Vue.js, AngularJS 1, Angular 2+, and React

In a nutshell, Onsen UI simplifies your development, works with any framework, and is future proof!

Interested in a deep dive? Check out our Onsen UI Architecture section.

What’s Included (Kitchensink)

Here you can try out the majority of Onsen UI’s components in a quick sample demo app (kitchen sink app). The two apps below are actually sharing the same source code but are styled to fit their respective platforms using the Auto Styling feature.

For those interested in the complete list of components, please take a look at the CSS Components and the Web Components.

Browser and Device Support

Onsen UI is fully optimized and tested for the following platforms.

Mobile iOS 9 and up Android 4.4.4 and up with WebView or Chrome browser (Android 4.0 and up with Crosswalk engine)

Desktop Latest version of Safari browser Latest version of Chrome browser



For other platforms, please be aware that some components or features may not work correctly. Please see Old Browser Support for details.

The First Onsen UI App

Now that you’re familiar with what Onsen UI is all about, it’s time to start creating your own app. For quicker installation, let’s use the CDN served files. First, create a file called index.html and paste the following HTML.

<!DOCTYPE html> <html> <head> <link rel="stylesheet" href="https://unpkg.com/onsenui/css/onsenui.css"> <link rel="stylesheet" href="https://unpkg.com/onsenui/css/onsen-css-components.min.css"> <script src="https://unpkg.com/onsenui/js/onsenui.min.js"></script> </head> <body> <ons-button onclick="alert('Hello World!')">Click Me</ons-button> </body> </html>

While this may be rudimentary, this example contains some important aspects of Onsen UI components as below.

You need to include two CSS files ( onsenui.css and onsen-css-components.min.css ) and one JavaScript file ( onsenui.min.js ).

and ) and one JavaScript file ( ). In the code above, <ons-button> component is used. It is our custom tag that represents a button. All Onsen UI branded components have the ons- prefix.

component is used. It is our custom tag that represents a button. All Onsen UI branded components have the prefix. Like other standard tags (or HTML elements), Onsen UI components have attributes (in this case onclick ), methods and event listeners. Read more in Attributes, Properties, Methods and Events.

Congratulations! You’ve covered all the basics to get started. Now find Onsen UI components (i.e. <ons-input> , <ons-icon> , <ons-carousel> …) from our collection, and put them in your app. It’s that simple.

Tips on native alert: You may have noticed, default alert() function does not fit with native app design. Therefore, Onsen UI provides ons.notification object for dialogs. Try replacing alert with ons.notification.alert !

Making Your Web & Hybrid App Feel Native

Even though an app may emulate the visual components of iPhone or Android, the goal of a seamless app is to ensure that touch & feel also meets users’ expectations. That’s where the users feel the “uncanny valley”.

To fill the gap, Onsen UI gives you the ability to simulate things like page transition animations and the ripple effect, and gives genuine and high quality feeling to your app. Such details make a huge difference.

In the above example, there are two pages defined by <ons-page> component. Then, <ons-navigator> component provides native-like page transition. If you want to make your app more native-like, please proceed to Fundamentals to learn how to fully utilize the details.

In Onsen UI, everything from visual widgets to small details are carefully crafted to help your application look fully native.

Useful Resources

Also check out these resources to get you up and running in no time.