Onsen UI: Hybrid App & PWA Framework

2.12.8 · active · verified Tue Apr 21

Onsen UI is an open-source, framework-agnostic HTML5 UI framework designed for creating native-feeling Progressive Web Apps (PWAs) and hybrid mobile applications. Built on Web Components, it provides a rich set of pre-built UI components that automatically adapt to both iOS (Flat) and Android (Material) design guidelines from a single codebase. It is currently at version 2.12.8, with an active release cadence focusing on bug fixes, performance improvements, and minor new features within the 2.x major line. Key differentiators include its pure JavaScript/Web Component foundation, allowing usage without any JavaScript framework, alongside official binding packages for popular frameworks like React, Angular, and Vue. It emphasizes ease of use, optimized animations for mobile, and seamless integration with Cordova/PhoneGap.

Common errors

```
ReferenceError: ons is not defined
```
cause The Onsen UI JavaScript file was not loaded or was loaded incorrectly, or in an ESM context, the 'ons' object was not explicitly imported or assigned to the global scope.

fix Ensure `onsenui.min.js` is included in your HTML `<head>` or before your scripts. If using ES Modules, ensure `import ons from 'onsenui/esm';` is present and potentially `window.ons = ons;` if relying on the global object.
```
Uncaught DOMException: Failed to execute 'define' on 'CustomElementRegistry': the name "ons-page" has already been used with this registry
```
cause The Onsen UI component scripts (or specific element modules in ESM) are being loaded multiple times, attempting to re-register a custom element that is already defined.

fix Check for duplicate script tags for `onsenui.min.js` or `onsenui.js`. If using ES Modules, ensure you are only importing `onsenui/esm` and individual element modules once across your application bundle.
```
Custom element 'ons-page' has not been defined
```
cause You are using an Onsen UI custom element tag in your HTML, but the corresponding JavaScript for that component has not been loaded or registered yet.

fix Verify that `onsenui.min.js` (or the specific ESM element imports like `onsenui/esm/elements/ons-page`) is correctly included and loaded before the custom element is rendered in the DOM. Place script tags at the end of `<body>` or use `ons.ready()` for DOM interactions.

Warnings

breaking The `expanded` CSS class for `ons-list-item` was renamed to `list-item--expanded`.
Fix: Update your CSS or class manipulation logic to use `list-item--expanded` instead of `expanded` for list item expansion styling.
breaking The `onClick` callbacks for `ons-tab`, `ons-back-button`, and `ons-speed-dial` no longer automatically prevent default browser behavior. You must now explicitly call `event.preventDefault()` within your callback if you wish to prevent default actions.
Fix: Review your `onClick` handlers for these components and add `event.preventDefault()` where default behavior (like navigating or opening/closing) should be suppressed.
gotcha When using Onsen UI in an ES Module (ESM) environment with a bundler (e.g., Webpack, Rollup), importing `onsenui` directly (`import 'onsenui';`) will include all components. For smaller bundle sizes, import the `ons` object from `onsenui/esm` and then manually import only the specific custom elements your application uses from `onsenui/esm/elements/`.
Fix: Refactor imports to use `import ons from 'onsenui/esm';` and then selectively import components like `import 'onsenui/esm/elements/ons-page';` for each required component.
gotcha Onsen UI relies heavily on Web Components. Direct DOM manipulation or framework-specific rendering might interfere with component lifecycle or styling if not done carefully. Ensure components are properly initialized and registered before use.
Fix: Prefer using Onsen UI's provided methods and attributes for interacting with components. When using a framework, leverage its official binding packages (e.g., `react-onsenui`, `vue-onsenui`) for proper integration.

Install

npm install onsenui npm
yarn add onsenui yarn
pnpm add onsenui pnpm

Imports

ons
wrong:
```
import { ons } from 'onsenui'; // For general use, not how the global 'ons' object is exposed via ESM
const ons = require('onsenui'); // CommonJS import for ESM-first library
```
correct:
```
import ons from 'onsenui/esm';
// ... then optionally individual components
import 'onsenui/esm/elements/ons-page';
```
For ES Module environments, import `ons` from `onsenui/esm` to get the global object, and individual elements from `onsenui/esm/elements/` to minimize bundle size. The UMD build (e.g., from CDN or direct script tag) makes `ons` globally available without explicit import statements.
OnsGlobal
```
import type { OnsGlobal } from 'onsenui';
```
TypeScript users can import the `OnsGlobal` type to correctly type the global `ons` object or the `ons` object imported from `onsenui/esm`.
ons-page (custom element)
```

<ons-page>
  <ons-toolbar>
    <div class="center">My App</div>
  </ons-toolbar>
  Page Content
</ons-page>
```
Onsen UI components are custom elements. They are automatically registered when the main Onsen UI script is loaded (via UMD bundle) or when specific element modules are imported in an ESM environment. Use them directly as HTML tags.

Quickstart

This quickstart demonstrates a minimal Onsen UI application using direct HTML and JavaScript, defining a main page with a toolbar and a button. It includes the necessary CSS and JavaScript files from a CDN, and uses `ons.ready()` to ensure the framework is initialized before interacting with components or displaying notifications.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover">
  <title>Onsen UI Quickstart</title>
  <link rel="stylesheet" href="https://unpkg.com/onsenui/css/onsenui.css">
  <link rel="stylesheet" href="https://unpkg.com/onsenui/css/onsen-css-components.css">
  <script src="https://unpkg.com/onsenui/js/onsenui.min.js"></script>
  <script type="text/javascript">
    // Ensure Onsen UI is ready before interacting with its components or global 'ons' object
    ons.ready(function() {
      console.log('Onsen UI is ready!');

      // Example: Pushing a new page programmatically
      document.addEventListener('init', function(event) {
        var page = event.target;

        if (page.id === 'main-page') {
          var button = page.querySelector('#push-button');
          button.onclick = function() {
            // The navigator exists if declared in HTML
            ons.notification.alert('Hello from Onsen UI!');
          };
        }
      });

      // Another way to push a page, e.g., after an event or data load
      // const navigator = document.querySelector('ons-navigator');
      // if (navigator) {
      //   navigator.pushPage('next-page.html', { animation: 'lift' });
      // }
    });
  </script>
</head>
<body>
  <ons-navigator swipeable id="app-navigator" page="main-page.html"></ons-navigator>

  <template id="main-page.html">
    <ons-page id="main-page">
      <ons-toolbar>
        <div class="center">Home</div>
      </ons-toolbar>

      <div class="content">
        <section style="margin: 16px; text-align: center;">
          <p>Welcome to Onsen UI!</p>
          <ons-button id="push-button">Say Hello</ons-button>
        </section>
      </div>
    </ons-page>
  </template>
</body>
</html>

view raw JSON →