Improve this

Troubleshooting and FAQ

How can I disable …?

Onsen UI automatically performs several optimizations, but the followings are fully optional and can be turned off at any time. If you would like to disable these, here’s how:

How can I force specific styles?

The auto styling feature displays flat design for iOS and Material Design for Android. Auto styling can be disabled with ons.disableAutoStyling() in order to display the default flat design on every platform. material modifier can be added manually to elements that should be displayed as Material Design.

However, it is also possible to fake the platform by running‘android’) or‘ios’) right after including onsenui.js. Note that changing the platform also affects other utilities like ons.platform.isAndroid().

During development, you can change the device view in the Developer Tools of your browser and refresh the page to update the styles. For instance, “iPhone 5” will show flat design whereas “Nexus 5” displays Material Design. Otherwise, append ?platform=android or ?platform=ios as a query string to the URL.

How can I use custom icon packs?

By default, Onsen UI imports Font Awesome, Ionicons and Material Design icons in onsenui.css file. A fa- prefix is automatically added if the provided icon name’s prefix does not match any of the default fonts. Since v2.8.0, this behavior can be avoided by calling ons.disableIconAutoPrefix() method right after including onsenui.js. Apart from this, custom icon packs can be added manually by just importing the corresponding CSS fonts. See also Reducing App Size#Removing Icon Packs for related information.

When adding custom icons such as <ons-icon icon="my-custom-icon"></ons-icon>, the class my is added to the element together with my-custom-icon in order to provide a common prefix-based selector. This way, all you custom icons can be adjusted together with the .my CSS selector. For example, if you find that the line-height is wrong for custom icons inside ons-toolbar-button elements, you can adjust them with the following rule:

.toolbar-button .my { line-height: ...; }

Pushing new pages is slow

If you are creating pages from separate files which, at the same time, contain other pages from even more files (e.g. pushing a tab bar), it can get a bit slow since there are many requests going on. In this case, you can use ons.preload([...]) method at any time to make requests and cache those templates beforehand.

Where is ons-scroller?

ons-scroller was a directive in Onsen UI v1 that had scrollable content. It was removed in Onsen UI v2 because it can be replaced with a simple div with a few CSS properties:

.scroller {
  display: block;
  height: 100%;
  overflow: auto;
  -webkit-overflow-scrolling: touch;
  -ms-overflow-style: none;
  -ms-scroll-snap-type: mandatory;

Alternatively, you can use ons-page for extended functionality (it doesn’t need to be fullscreen) or a ons-carousel without auto-scroll attribute.

Common Error Messages

Old Browsers

As mentioned in the Browser and Device Support, some older browsers will not work properly due to the lack of some recent functions. We only test on the Webkit family platforms. If you need Onsen UI to work on the following environment, please try adding polyfills to fill the gap to the latest HTML5 standard.

Headless Testing

Jest, jsDom, PhantomJS, etc. are very useful tools for headless testing. However, you need to make sure that your testing suite supports the latest Web APIs and is compatible specifically with Custom Elements (part of Web Components). As of early 2017, none of the mentioned tools support it out of the box.

As a suggestion, try Karma + Chrome headless (+v59).