We’ll cover how to upgrade to a new Quasar version in your project, both for UMD and using the Starter Kit. Then we’ll go on to discuss how you can migrate v0.15 to v0.16 and your pre v0.15 project to v0.15+.
This applies when upgrading from v0.15+ to a newer Quasar version, including v0.16.
Quasar v0.15+ requires Node.js version 8.9.0 or greater
Simply replace the version string in all the CSS and JS tags that refer to Quasar to the newer version.
As you may have noticed, the only dependency in your project (unless you’ve also installed a linter or your own deps) is
quasar-cli. All you need is to update this dependency.
$ yarn add --dev quasar-cli@latest
Quasar CLI is installed both globally and locally. When you issue a Quasar command, the global installation defers to the project locally installed Quasar CLI. This allows you to skip writing npm scripts in your package.json (for Quasar commands), and also it allows you to run different Quasar versions in multiple projects.
Watch for Quasar CLI version. It’s not the same thing as Quasar version. Type
$ quasar info. All you need to know is that the major and minor part of Quasar CLI version matches Quasar version. So for example installing latest Quasar CLI v0.15.x will ensure you are using latest Quasar v0.15.x. While working on v0.15.x, no breaking changes will occur, so you are safe (& recommended) to upgrade to latest Quasar CLI as it’s released.
Sometimes after you npm install a package, or even update current packages, might screw things up. You’ll get errors that some packages are missing and you need to install them. In such cases, delete node_modules and package-lock.json and npm install again.
Same goes for Yarn. In case you get errors, delete node_modules and yarn.lock then install again.
The difference between Quasar v0.15.x and v0.16 is minimal. No big breaking changes as you can see below. The only reason for bumping Quasar’s version is to maintain consistency (same major + minor version) with Quasar CLI (which got an important update: webpack 4, babel 7, Workbox, electron-builder support, ionicons v4 and many more).
Upgrading from v0.15.x should be seamless if you are using Quasar CLI – which will guide you to do some minor changes to your project folder. Note that Ionicons v4 has breaking changes, so if you are using it in your project, then you need to update each such icon to its new name.
If you face any problems, there is probably something conflicting in your npm modules. It is either babel, webpack or eslint. The console messages will tell you more about what is wrong.
Remember you’ll be using Webpack 4, so all your webpack plugins must be compatible with it. For example, you need to upgrade to a newer
babel-eslintetc package if you already have it in your package.json as dev dependency.
If you’re using ESLint, make sure you have these in your package.json (minimum version required):
If you are seeing babel issues when you run
quasar dev, then you have probably installed a package that is using babel-core instead of @babel/core - such as
cypress-vue-unit-test. To find out which one it is, run:
npm ls babel-core and then remove the offending source.
# cd into project folder
- QIcon: removed “mat” & “ios” props for performance reasons (use
:name="$q.theme === 'mat' ? val : otherVal"instead)
- Removed utils > dom > viewport() method (use window.innerHeight/innerWidth instead)
- Updated Quasar ionicons set to Ionicons v4 – compatible with firstname.lastname@example.org
There’s been A LOT of work done for v0.15. The Quasar CLI has been rewritten from scratch to allow for a stellar development experience (Mobile App developers and Electron will fall in love with it!). Only one starter kit is required in order to handle websites, PWAs, Mobile Apps and Electron Apps. Building any of those is a matter of just adding a parameter to the dev/build command.
Furthermore, you can now use an UMD/standalone version of Quasar to embed in an existing project. No build step is required.
Take some time to read all “Guide” pages once again. It will help you understand the true power of Quasar v0.15+ and what you can do with it.
So, what is new and what has changed? Everything has been polished. The full list of enhancements and new features is exhausting. We’ll try to cover the major parts only. This is just a guide to get you started so that you know where to look in docs for things that have changed.
First we make sure we update the globally installed Quasar version (needs to be at least v0.15). Then we create a new project folder:
# Node.js >= 8.9.0 is required.
$ yarn global add quasar-cli@latest
$ npm install -g quasar-cli@latest
# Then we create a project folder with Quasar CLI:
$ quasar init <folder_name>
Observe the new project structure. Start to port out files to the new project folder, taking into account the far superior structure. Using the new starter kit will allow you to take advantage of future seamless upgrades! In any case, do not simply copy your
/src folder over to the new starter kit.
You’ll notice the new starter kit doesn’t provide a
/config folders. They are no longer required. Everything can be easily configured from
/quasar.conf.js now. You don’t need to know Webpack. More Info.
Yes. It’s no longer there because you don’t need it anymore. For initialization code and importing libraries into your website/app, read about App Plugins.
You’re no longer required to import Quasar components and directives anywhere in your app. Simply configuring
framework Object will suffice. More Info.
Yes, this refers to Action Sheet, Notify (replacement of Toast and Alert), LocalStorage/SessionStorage and so on. They are available globally or under the Vue
$q Object injection, and need to be specified in
/quasar.conf.js > framework > plugins in order for them to be available.
- Flex CSS gutter classes
- QLayout & co. You’ll love the new features! Be sure to check this out. Major improvements in syntax and flexibility. Some breaking changes, like slots no longer being used.
- QBtn (new features!)
- QToolbar (small update regarding buttons)
- QBreadcrumbs (powerful component instead of just CSS)
- QPagination (major improvements)
- QCollapsible (new powerful features!)
- QTable (replacing QDataTable – full customization now!)
- Lists & List Items – more options, better control, “dark” theme
- QTree (the most advanced you’ll ever see and need!)
- ActionSheet (now as a Quasar Plugin & QActionSheet component too! – has new features too)
- Dialog (now as a Quasar Plugin & QDialog component too for unlimited flexibility! – has new features too)
- QModal - Easier to use than ever! Now with full v-model support.
- QPopover & QTooltip - new animation, ability to close it without the need of a Vue reference (through
v-close-overlaydirective), full support for v-model now
- Loading (now as a Quasar Plugin)
- QCarousel - Easier to use. Fully customizable!
- Transitions - No need for QTransition anymore! Minimum overhead, better performance.
- QAlert - new features
- QChat - new features
- TouchSwipe, TouchHold and TouchPan - Much better implementation, more control. Read about these directive’s modifiers.
- AppFullscreen & AppVisibility - Now as Quasar Plugins, with reactive state properties that can be used in Vue watchers
- QUploader - new features & design
Also notice QInlineDatetime has been renamed to QDatetimePicker.
- Spacing CSS classes
- QTable - It’s on the Revamps list too, but it sure deserves a place here too. Prepare for next level Data Tables, now fully customizable! Check out the demo too.
- QEditor - Quasar’s own WYSIWYG approach! This alone would deserve its own section.
- Notify - A merge between Toast and Alert, with flexible positioning and awesome animations.
- QColor - Color Picker!
- New button types: QBtnGroup and QBtnDropdown
- QBtnToggle - A radio-like component, but with buttons
Be sure to check out the Internationalization for Quasar Components.
You can now tell Quasar to use one of Fontawesome, Ionicons, MDI or Material Icons for its components. You are no longer required to include Material Icons. You can use any of these packs as default.
Also, small change for Fontawesome icons:
<!-- pre v0.15 -->
<q-icon name="fa-paypal fab" />
<!-- v0.15+ -->
<!-- Copy paste fontawesome icon class as it's in fontawesome docs now -->
<q-icon name="fab fa-paypal" />
You can use
$q injection for convenience, accessing Quasar Theme, Quasar I18n, Quasar Platform, and many more. Quasar Plugins add functionality to it. Read doc page, especially if you build Cordova or Electron apps.
- Global Event Bus (Events) – no longer needed. Use Vue root component events instead. More Info
- QFixedPosition – now replaced by a more powerful QPageSticky
- QSideLink – no longer required! Simply use a QItem or whatever component you want and bind an
- Alert and Toast as methods. They’ve been merged into Notify.
- HTML Table. You can however check code from v0.14 and embed it yourself into your app.
- Image Gallery - no longer needed. The new QCarousel is so powerful that you’ll immediately see the benefit of switching to it.
- QTransition - no longer required. Simply use Vue’s
<transition-group>) instead. More Info
- QDatetimeRange - it’s so easy to simply write two QDatetime side by side that this component is simply not required anymore; this allows you full flexibility too.
The following upgrade guide for QLayout barely scratches the surface, but it’s a starting point.
<!-- v0.14 -->
We upgrade it to v0.15+. Notice that in order for us to place navigation tabs on header (for Material) and on Footer (for iOS), we also write a NavTabs component. Notice no slots, no QSideLink, “flat round dense” buttons, v-model on left/right drawers, QLayout* components:
<!-- layout component -->
<q-layout ref="layout" view="hHr LpR lFf">
<!-- Header -->
<q-btn flat round dense icon="menu" @click="leftSide = !leftSide" />
<span slot="subtitle">Optional subtitle</span>
<q-btn flat round dense icon="menu" @click="rightSide = !rightSide" />
<!-- Navigation for Material theme -->
<nav-tabs v-if="$q.theme === 'mat'" />
<!-- Left Side Panel -->
<q-layout-drawer v-model="leftSide" side="left">
<q-list no-border link inset-separator>
<q-item-side icon="school" />
<q-item-main label="Docs" sublabel="quasar-framework.org" />
<!-- Right Side Panel -->
<q-layout-drawer v-model="rightSide" side="right" :breakpoint="1100">
Right Side of Layout
<!-- sub-routes get injected here: -->
<!-- Footer -->
<!-- Navigation for iOS theme -->
<nav-tabs v-if="$q.theme === 'ios'" />
<!-- nav-tabs component -->
<q-route-tab slot="title" icon="view_quilt" to="/test-layout/about" replace hide="icon" label="About" />
<q-route-tab slot="title" icon="view_day" to="/test-layout/toolbar" replace hide="icon" label="Toolbar" />
<q-route-tab slot="title" icon="view_day" to="/test-layout/tabs" replace label="Tabs" />
<q-route-tab slot="title" icon="input" to="/test-layout/drawer" replace label="Drawer" />
In previous versions you would listen for
@change event to detect changes. Now you can listen to
@input for immediate changes or
@change for lazy update. Vue
v-model.lazy support is a pending change, so until then you can use the equivalent form (details below).
<!-- QInput example -->
You’ll notice all form components have been polished. Also, you’ll be pleasantly surprised by new properties. To name just a few: “hide-underline”, “inverted-light”, “dark” or “warning” (for highlighting a warning state).
Prior to v0.15, form components had a default margin. This was removed to allow easier customization. You can now use the new Spacing CSS classes to do it.
QCheckbox now supports an indeterminate state as well. You can specify a value for “true”/“false”/“indeterminate” states, so it no longer operates with Booleans (or Arrays) only.
QDatetime now doesn’t require the “Set” button when using Popovers. Clicking on a date will simply select it and close the popover.
QChipsInput (& QChips) have new props that allow for better customization now.
Modals, Popovers, Tooltips, Layout Drawer, Dialog, Notify (just to name a few) now use Promises instead of taking a callback parameter. This allows you to take advantage of async/await and simplifies your code.
You were also used to using Vue refs for a few components (Layout left/right drawer, Modals, …). This is no longer necessary. You can use a “v-model” instead to show (open) / hide (close) them. This wasn’t quite possible pre v0.15 because you needed for them to close in order to, as an example, navigate away. Now it’s no longer needed, so a Boolean scoped variable will suffice.
Some components, like QItem or QCard & co now need the
.native modifier for binding to native DOM events like
click. A general rule is: if
@click is not mentioned in the component’s docs Vue Events section, then you need to use the native modifier.
<!-- prior to v0.15 -->
A few Quasar components were of functional type. These pass native events right through, so there’s no need to add the native modifier. But during a thorough benchmarking session it turned out having these as regular components meant better performance due to a number of reasons. Switching these components from functional to regular adds this small breaking change where you need to use the native modifier.
You still can! Only now it’s even better, due to
/quasar.conf.js features. More Info
All components using popups, like Modal, Dialog, Popover, Context Menu, now support a much simplified way of closing them. Instead of using a Vue reference, which is troublesome for some use cases, you can simply add
v-close-overlay to the element/component that you wish to close the popup. This directive listens for the
@click event, determines the first parent popup component and closes it.
<q-btn label="I got a Popover">
Unfortunately, the automatic handling of back button was a one of the features that was the hardest to comprehend. It required you to handle Vue references (which beginners on Vue were struggling with) and didn’t fully allow you to connect components like Drawers & Modals to Vuex in an easy way. Now it only works on Mobile Apps (for example Android has a back button that is handled by Quasar). The removal of this feature for websites greatly simplify your code:
While QBtn still allows you to specify icon and label as children nodes, it is now recommended that you use the “icon” and “label” props instead:
<q-btn icon="map" label="See map" />
Be sure to check out the new button types and props too.
The Quasar CLI v0.15+ is not compatible with pre-0.15 apps. You can install the latest CLI globally while still supporting
quasar commands in legacy apps by adding
quasar-cli as a development dependency. To support 0.14 and earlier you need quasar-cli v0.6.5.
$ yarn add --dev email@example.com
This will add the legacy
quasar CLI tool to your projects
Use the npx tool (automatically installed alongside npm) to run
quasar from your local node modules. For example:
$ npx quasar dev