{"id":15156,"library":"onsenui","title":"Onsen UI: Hybrid App & PWA Framework","description":"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.","status":"active","version":"2.12.8","language":"javascript","source_language":"en","source_url":"https://github.com/OnsenUI/OnsenUI","tags":["javascript","phonegap","cordova","web-components","react","components","angular","vue","hybrid","typescript"],"install":[{"cmd":"npm install onsenui","lang":"bash","label":"npm"},{"cmd":"yarn add onsenui","lang":"bash","label":"yarn"},{"cmd":"pnpm add onsenui","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { ons } from 'onsenui'; // For general use, not how the global 'ons' object is exposed via ESM\nconst ons = require('onsenui'); // CommonJS import for ESM-first library","symbol":"ons","correct":"import ons from 'onsenui/esm';\n// ... then optionally individual components\nimport 'onsenui/esm/elements/ons-page';"},{"note":"TypeScript users can import the `OnsGlobal` type to correctly type the global `ons` object or the `ons` object imported from `onsenui/esm`.","symbol":"OnsGlobal","correct":"import type { OnsGlobal } from 'onsenui';"},{"note":"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.","symbol":"ons-page (custom element)","correct":"\n\n \n
\n \n \n\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Update your CSS or class manipulation logic to use `list-item--expanded` instead of `expanded` for list item expansion styling.","message":"The `expanded` CSS class for `ons-list-item` was renamed to `list-item--expanded`.","severity":"breaking","affected_versions":">=2.12.0"},{"fix":"Review your `onClick` handlers for these components and add `event.preventDefault()` where default behavior (like navigating or opening/closing) should be suppressed.","message":"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.","severity":"breaking","affected_versions":">=2.12.0"},{"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.","message":"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/`.","severity":"gotcha","affected_versions":">=2.8.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure `onsenui.min.js` is included in your HTML `` 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.","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.","error":"ReferenceError: ons is not 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.","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.","error":"Uncaught DOMException: Failed to execute 'define' on 'CustomElementRegistry': the name \"ons-page\" has already been used with this registry"},{"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 `` or use `ons.ready()` for DOM interactions.","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.","error":"Custom element 'ons-page' has not been defined"}],"ecosystem":"npm"}