onsenui

library2.12.8jsnpmunverified

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.

web-framework

npm install onsenui

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ONSENUI

onsenui

web-frameworkjavascriptv2.12.8

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ons

✓ import ons from 'onsenui/esm'; // ... then optionally individual components import 'onsenui/esm/elements/ons-page';

✗ 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

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.

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>

Debug

Known issues

breakingThe `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.

affects: >=2.12.0

breakingThe `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.

affects: >=2.12.0

gotchaWhen 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.

affects: >=2.8.0

gotchaOnsen 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.

affects: >=2.0.0

Errors

Common errors & fixes

ReferenceError: ons is not defined

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

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

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.

Upgrade

Version history

2.12.8latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/OnsenUI/OnsenUI ↗

packagehttps://www.npmjs.com/package/onsenui ↗

homepagehttps://onsen.io ↗