Improve this

Vue 2

Before reading this section, we suggest you reading Getting Started and Fundamentals to grasp the basics of Onsen UI. Don’t worry, it won’t take more than 5 minutes.

Vue bindings for Onsen UI (VueOnsen) provide Vue 2 components and directives that wrap the core Web Components and expose a Vue-like API to interact with them.

In this guide, we’ll walk you through how to set up Onsen UI + Vue and cover basics to get started.

Setting up a new project

If you install version 3 of the Vue CLI, you can take advantage of features that make setting up an Onsen UI + Vue project really simple.

First, make sure you have at least version 3 of the CLI (the @vue/cli package, not vue-cli).

npm install -g @vue/cli

Now you can set up your app by using the create command. This will guide you through various options. Please note: For starting your Onsen UI phone app do not add the Progressive Web App (PWA) support option which is for deploying to a website and not to a device.

vue create my-onsen-app

Installation

Once you have a Vue project set up, you just need to install the core Onsen UI package (onsenui), and the Vue bindings (vue-onsenui). Inside the project root, run:

npm install onsenui vue-onsenui

Setup

Inside your project’s main file (usually main.js), Onsen UI’s files need to be imported.

// Webpack CSS import
import 'onsenui/css/onsenui.css';
import 'onsenui/css/onsen-css-components.css';

// JS import
import Vue from 'vue';
import VueOnsen from 'vue-onsenui'; // This imports 'onsenui', so no need to import it separately

Vue.use(VueOnsen); // VueOnsen set here as plugin to VUE. Done automatically if a call to window.Vue exists in the startup code.

Hello World App

To get started, let’s create a simple Hello World application. Projects set up using the Vue CLI are single file components. This means the HTML, CSS and JS are all contained in one .vue file. The default project created by the CLI will have at least an App.vue file. Edit it to look like this.

<template id="main-page">
  <v-ons-page>
    <v-ons-toolbar>
      <div class="center">Title</div>
    </v-ons-toolbar>

    <p style="text-align: center">
      <v-ons-button @click="$ons.notification.alert('Hello World!')">
        Click me!
      </v-ons-button>
    </p>
  </v-ons-page>
</template>

<style>
  /* CSS goes here */
</style>

<script>
  // Javascript goes here
</script>

Projects created by the Vue CLI come with various scripts, including one to serve the project so you can preview it in the browser.

npm run serve

Open the given URL in your browser. If you click the button, you will see an alert dialog. That’s it!

To continue from here, take a look at the Onsen UI Vue Components list. You should also take a look at our Kitchensink Example which shows all the Onsen UI components being used with Vue. For more information about Vue itself, we recommend reading the official Vue docs. If you want to know more about how the bindings word, keep reading below.

Advanced

Understanding Vue Components

Onsen UI’s Vue components are simple wrappers around inner Custom Elements in most of the cases. This means that a Vue Component takes some props and translates them into DOM properties, DOM attributes or method calls for the Onsen UI core. It also listens for native events and fires the corresponding Vue events. If you inspect the DOM you will likely see a bunch of ons-* components without v-* prefix (these are real HTML elements). You can have a look at the implementation here.

Since v-ons-* components compile into ons-* DOM elements, you can use this knowledge to style your component with tag names as well. For example, if you want to style a button, you should target ons-button, not v-ons-button.

VOnsPage Compilation

v-ons-page component compiles into ons-page custom element. This element, at the same time, processes its content and filters scrollable and fixed elements. Scrollable content is moved into a special div.page__content wrapper. This behavior might create issues under some specific situations, like using v-for with asynchronous data. To avoid any possible issue, manually providing a div.content element is recommended:

<v-ons-page>
  <v-ons-toolbar></v-ons-toolbar>

  <div class="content">
    <!-- Scrollable content here -->
    <v-ons-input></v-ons-input>
    <div v-for="item in asyncAjaxItems"></div>
  </div>

  <!-- Fixed content here -->
  <v-ons-fab></v-ons-fab>
</v-ons-page>

See also Components Compilation section for more details about this.

The $ons object

The original ons object is not available in the global scope in Vue applications. Instead, it is provided in every Vue instance as this.$ons through Vue’s protoytpe:

<v-ons-button @click="$ons.notification.alert('Hi there!')">
  Click me
</v-ons-button>
Event Handling

DOM events fired by Onsen UI elements are translated into Vue events in the corresponding components. For example, v-ons-navigator can handle a postpush event with @postpush="...".

From `vue@2.4.0andvue-onsenui@2.1.0onwards, native DOM events are passed down to the children. This means thatwill work __without__nativemodifier. Prior to these versions,@change.native=”…”` syntax is required. Note that these events are still DOM events and, as such, Vue DevTools won’t show any Vue event for these.

The exception to this is click event, which is turned into a Vue event in some components. The reason is that click event is used to override default behaviors:

<v-ons-back-button @click.prevent="pageStack.splice(1)"></v-ons-back-button>

The previous example overrides the v-ons-back-button default behavior, popping 1 single page, and resets the stack to the first page instead. The prevent modifier is just calling $event.preventDefault().

Additionally, components that are capable of handling Cordova’s backbutton event (Android’s back button), can listen for this event with @deviceBackButton handler.

<v-ons-dialog @deviceBackButton="$event.callParentHandler()"></v-ons-dialog>

More information about this event in the original Cordova-specific Features section.

Inputs and v-model

Input components in Onsen UI (such as v-ons-input or v-ons-checkbox) support Vue’s v-model directive:

<v-ons-input v-model="something"></v-ons-input>

The only exceptions are v-model modifiers, which are not supported by custom components as of `vue@2.3, unfortunately. However, there is a workaround for the most important one, thelazy` modifier:

<v-ons-input v-model="something" model-event="change"></v-ons-input>

This will update the model on change events instead of input (default). The rest of the modifiers can be easily implemented in other ways.

It is also possible to bind arrays to v-ons-checkbox or v-ons-switch just like normal <input type="checkbox">, and make radio groups with v-model for v-ons-radio.

ES Modules in Vue apps

Apart from the full vue-onsenui bundle, an ESM version is provided under vue-onsenui/esm since `vue-onsenui@2.4.0`. The main benefit of using this distribution is that components you don’t use will be left out of the bundle without relying on tree shaking algorithms. This helps reduce your app’s size. See our core guide to ES Modules for more information.

import Vue from 'vue';
import VueOnsen from 'vue-onsenui/esm';
import VOnsPage from 'vue-onsenui/esm/components/VOnsPage';
import VOnsToolbar from 'vue-onsenui/esm/components/VOnsToolbar';

Vue.use(VueOnsen);
Vue.component(VOnsPage.name, VOnsPage);
Vue.component(VOnsToolbar.name, VOnsToolbar);

The previous code imported VueOnsen (which is just an alias for $ons object) and registers it in Vue. This step does not include any components at all, unlike import VueOnsen from 'vue-onsenui' would do. Therefore, we can import the necessary components manually and register them as global Vue components (optional). Components have a name property that can be used for registering them in Vue (v-ons-page, v-ons-button, etc).

Since importing and registering many components can be very verbose, we recommend creating an extra file with the desired list of components using the following export syntax:

// onsenui-components.js
export { default } from 'vue-onsenui/esm/components/VOnsToolbar';
export { default } from 'vue-onsenui/esm/components/VOnsNavigator';
export { default } from 'vue-onsenui/esm/components/VOnsPage';
export { default } from 'vue-onsenui/esm/components/VOnsCarousel';

Then, simply import and register everything in your main file:

// main.js
import Vue from 'vue';
import VueOnsen from 'vue-onsenui/esm';
import * as OnsenComponents from './onsenui-components.js';

Vue.use(VueOnsen);
Object.values(OnsenComponents).forEach(c => Vue.component(c.name, c));

In case you don’t want to use the default c.name provided, you can assign a new one with export { default as CustomName } from 'vue-onsenui/esm/component/...;' and then using the object key instead of c.name.

Making a Cordova app

Turning your Onsen UI + Vue project into a Cordova app is simple using the vue-cli-plugin-cordova plugin. Simply follow the instructions there to get going.

Vue Bindings FAQs

How do I set up global Onsen UI options?

The main guide describes how to disable or set some global features “right after including onsenui.js in the app”. This means that it must take effect before any component is rendered. Since the ons object is not provided globally, we need to use the $ons object at the very first possible location:

import Vue from 'vue';
import VueOnsen from 'vue-onsenui';
Vue.use(VueOnsen);

new Vue({
  el: '#app',
  render: h => h(...),
  beforeCreate() {
    this.$ons.disableAutoStyling(); // Or any other method
  }
})

This way, changes take effect before any component is rendered.

How do I pass data to the next page in the navigator?

A Navigator’s pages are sibling elements, which means that communication among them in Vue is fairly challenging. Vuex is a good solution for this, but not the only one. When you push a new page component and want to add some initial data, you can simply extend it:

import nextPage from 'nextPage.vue';
// ...

pageStack.push({
  extends: nextPage,
  data() {
    return {
      myCustomDataHere: 42
    };
  }
})

In order to send data back to the previous page before popping, take a look at Vue state management.

Can I use Vuex with Onsen UI?

Absolutely. Vuex is a good solution for component communication. If you feel you have too many props and events, Vuex may be a good fit. For an example of Onsen UI + Vue + Vuex, see the kitchensink app.

What about vue-router?

Onsen UI provides its own routing components: v-ons-navigator, v-ons-tabbar and v-ons-splitter. These components can be mixed in many ways to achieve the desired route pattern. This is generally enough for mobile single-page application, so there is no need to plug an external router.

However, for those who really want to integrate vue-router, it is fully compatible with Onsen UI. It simply has to be integrated with the three routing components mentioned above.