Improve this

Getting Started

Prefer to watch rather than read? Here is our video tutorial to help you get started.

The official guide assumes basic level knowledge of HTML, CSS, and JavaScript. If you are totally new to JavaScript development, let’s work on learning the basics while reading through the guide.

What is Onsen UI?

Onsen UI is…

Onsen UI enriches the user’s experience for mobile web apps with natively designed UI elements. It fits well for developing a mobile web app (also referred to as Progressive Web Apps). Onsen UI is also great for developing a hybrid app by using Cordova. For more information on this type of implementation, see Deploy to PWA & Cordova.

Future Proof Architecture

Under the hood, Onsen UI consists of three layers:

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

In short, it simplifies your development, works with any framework, and is future proof!

Interested in diving deeper? Check out our Onsen UI Architecture section.

What’s Included (Kitchensink)

Here you can get to try out almost all 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

Since Onsen UI is primarily designed for iOS and Android devices, it is fully optimized and tested under the following platforms.

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

The First Onsen UI App

Now that you’re familiar with what Onsen UI is all about, it’s time to actually start creating your own app. For quicker installation, let’s use the CDN served files. Let’s 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’s components.

Congratulations! You’ve covered all basics for getting started. Just 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.

Tip (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 an iPhone or Android, the goal of a seamless app is to ensure that touch & feel does not disrupt the expected user experience. That’s where the users feel the “uncanny valley”.

To fill the gap, Onsen UI gives you the ability to simulate page transition animations, the ripple effect, and genuine and high quality feeling components all to help the user experience. Details make the 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

Onsen UI has a couple of projects to help you get started right away.