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 3 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.
The easiest way to create a new Onsen UI + Vue 3 project is with Vite.
Make sure npm is installed and run
npm init vue@latest
This command will take you through the steps to create a new Vue project.
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
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 { createApp } from 'vue';
import App from './App.vue';
import VueOnsen from 'vue-onsenui'; // This imports 'onsenui', so no need to import it separately
const app = createApp(App);
app.use(VueOnsen); // VueOnsen set here as plugin to VUE.
If you are using the ESM build of vue-onsenui (the default), you also need to register the components your app will use. To register all components, add the following in your project’s main file:
import * as components from 'vue-onsenui/esm/components';
// Register all vue-onsenui components
Object.values(components).forEach(component =>
app.component(component.name, component));
If you want to use the UMD build instead of the ESM build, see UMD and ESM builds. When using the UMD version, there is no need to register Onsen UI components.
If you are having trouble with the setup steps, check out the example project for a complete configuration.
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 with Vite come with various scripts, including one to serve the project so you can preview it in the browser.
npm run dev
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 3 Components list. For more information about Vue itself, we recommend reading the official Vue docs. If you want to know more about how the bindings work, keep reading below.
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.
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 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 global configuration:
<v-ons-button @click="$ons.notification.alert('Hi there!')">
Click me
</v-ons-button>
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="...".
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.
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>
By default, this will update on the input event. To use a different event, such as change, set the model-event prop:
<v-ons-input v-model="something" model-event="change"></v-ons-input>
This will update the model on change events instead of input (default).
vue-onsenui is available as two different types of builds: the UMD build and the ESM builds.
The default is the ESM build, which is the best choice for modern browsers and bundlers. The ESM build requires that you register the Onsen UI components that your app will use. This allows you to only include the components you need, which helps reduce app size.
import * as components from 'vue-onsenui/esm/components';
// Register all vue-onsenui components
Object.values(components).forEach(component =>
app.component(component.name, component));
If you want to use the UMD build instead of the ESM build, add the following to your vite.config.js:
export default defineConfig({
plugins: [vue()],
resolve: {
alias: {
'vue-onsenui': 'vue-onsenui/dist/vue-onsenui.js'
}
},
optimizeDeps: {
include: ['vue-onsenui']
},
build: {
commonJsOptions: {
include: [/vue-onsenui/]
}
}
})
When using the UMD build, there is no need to register Onsen UI components.
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 { createApp } from 'vue';
import VueOnsen from 'vue-onsenui';
const app = createApp({
beforeCreate() {
this.$ons.disableAutoStyling(); // Or any other method
}
})
app.use(VueOnsen);
This way, changes take effect before any component is rendered.
A Navigator’s pages are sibling elements, which means that communication among them in Vue is fairly challenging. Pinia 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
};
}
})
Absolutely. Pinia is a good solution for component communication. If you feel you have too many props and events, Pinia may be a good fit. For an example of Onsen UI + Vue + Pinia, see the examples app.
For most apps, upgrading from vue-onsenui for Vue 2 to vue-onsenui for Vue 3 should be a straightforward process. However, along with the changes needed to upgrade a Vue 2 project to a Vue 3 project, there are some specific vue-onsenui breaking changes that need to be accounted for.
We recommend reading through the official Vue 3 Migration Guide first for any general Vue changes unrelated to Onsen UI that you need to make.
For a full list of changes, see the CHANGELOG.
If you are getting stuck, check out the examples app for a full configuration, or the Onsen UI playground for specific examples.
The first step is to install vue-onsenui for Vue 3. vue-onsenui v3+ is written for Vue 3, and vue-onsenui v2.x.x is for Vue 2.
To install vue-onsenui v3 and its corresponding onsenui version, run:
npm install --save vue-onsenui@latest onsenui@latest
Note that you need to have already installed Vue 3 or this command will throw an error.
In Vue 2, vue-onsenui was loaded by calling Vue.use in the app’s main file (usually main.js). Vue 3 replaces the global Vue API with createApp, which creates an app instance that can be loaded with vue-onsenui.
In your app’s main file, replace Vue.use with app.use:
import { createApp } from 'vue';
import App from './App.vue';
import VueOnsen from 'vue-onsenui';
const app = createApp(App);
app.use(VueOnsen); // this was previously Vue.use(VueOnsen)
vue-onsenui has two different builds: the UMD build, and the ESM build. In vue-onsenui v3, the default build switched from UMD to ESM, which is best for bundlers and modern browsers. The ESM allows you to only register the vue-onsenui components that your app will actually use, reducing app size. The UMD build automatically registers all components.
This means that when using the default vue-onsenui build, you must now register the components you want to use. To register all components, add the following to the app’s main file:
import * as components from 'vue-onsenui/esm/components';
// Register all vue-onsenui components
Object.values(components).forEach(component => app.component(component.name, component));
To register a single component:
import VOnsButton from 'vue-onsenui/esm/components/VOnsButton';
app.component(VOnsButton.name, VOnsButton);
For more details about UMD vs ESM, see UMD and ESM builds.
In vue-onsenui v3, some props had name changes. The main changes are:
options.animation and options.animationOptions are renamed animation and animationOptions for all components.modelValue prop and update:modelValue event are now used instead of modelProp prop and modelEvent event. However, the modelEvent prop is unchanged.index prop and update:index event have been renamed to activeIndex and update:activeIndex.For a full list of changes, see the CHANGELOG.
In vue-onsenui v2, VOnsNavigator was passed a pageStack prop which it directly manipulated. vue-onsenui v3’s navigator keeps its own internal representation of the page stack, which:
pageStack propupdate:pageStack event when the page stack changes internally (such as when the user swipes to pop the page or presses the device back button).This behaviour allows VOnsNavigator to be used with v-model, which will create a two-way binding to keep the page stack prop and the internal page stack in sync. If your existing app has an instance of VOnsNavigator, just add v-model in front of the pageStack prop:
<v-ons-navigator v-model:page-stack="pageStack"></v-ons-navigator>
Due to changes in how watchers work in Vue 3, VOnsNavigator no longer supports changing the page stack using methods that mutate the page stack array, such as Array.prototype.push and Array.protoype.pop. Instead, the whole value of the page stack prop should be replaced using methods such as Array.prototype.slice or the spread syntax.
pageStack.push(page), use pageStack = [...pageStack, page].pageStack.pop(), use pageStack = pageStack.slice(0, -1).pageStack = [pageStack[0]].Vue 3 may also warn that pages pushed to the navigator were made reactive objects. You can fix this warning by wrapping components with markRaw:
import { markRaw } from 'vue';
export default {
data() {
return {
pageStack: [markRaw(page1)]
};
},
};
In vue-onsenui v3, the navigator’s popPage prop has been removed. This prop was used to specify what should happen when a page is popped due to user interaction, such as pressing the device back button or swiping to pop.
If you were using the popPage prop to update a mutable value, popPage can be safely removed and the mutable value will be updated with v-model:page-stack="someMutableValue".
For other use cases of popPage, you should now specify which type of user interaction to overwrite:
@deviceBackButton.prevent="deviceBackButtonHandler".@postpop="postpopHandler". The event object contains a key swipeToPop which can be used to detect if the postpop was triggered by a user swiping to pop.@click.prevent to the VOnsBackButton. Alternatively, if you just need to do some update after the page has popped, do the same as swipe to pop above, but use the onsBackButton event key instead of swipeToPop.The vue-onsenui v3 version of VOnsLazyRepeat now requires that an object be returned by renderItem instead of a Vue instance. In most cases, this just means removing new Vue and returning the component object directly:
export default {
data() {
return {
renderItem: i => ({ // The object is returned here. Before, this would have been `new Vue`.
template: `<v-ons-list-item :index="index" :key="index">#{{ index }}</v-ons-list-item>`,
data() {
return {
index: i
};
}
})
};
}
};
The value of VOnsPopover’s target prop must now be a Vue ref.
<v-ons-toolbar-button ref="myToolbarButton">Test</v-ons-toolbar-button>
<v-ons-popover :target="$refs.myToolbarButton">
Popover
</v-ons-popover>