Upgrading from older v1 to latest v1

With UMD

Simply replace the version string in all the CSS and JS tags that refer to Quasar to the newer version.

With Quasar CLI

# run these commands inside
# of a Quasar v1 project

# check for upgradable packages
$ quasar upgrade

# do the actual upgrade
$ quasar upgrade --install

With Vue CLI

$ yarn upgrade quasar@1

You may also want to make sure you have the latest of @quasar/extras package too:

$ yarn add @quasar/extras@latest

Upgrading from 0.x to v1

Before you start down this journey of upgrading Quasar Legacy to Quasar v1 you should know a few things:

1. Read the documentation before asking questions on Discord server or forums.
2. Prepare a CodePen so staff can help you.
3. Dig into the Quasar source code (it’ll help you understand the framework as well as teach you best practices for programming with Vue).
4. Don’t use framework components as mixins unless absolutely necessary (wrap them if you need).
5. Don’t target inner component stuff with CSS selectors unless absolutely necessary.
6. We recommend yarn whenever possible because of its speed and efficient use. However, when using globals, we still recommend using npm, especially if you use nvm (Node Version Manager).
7. Use git for repository management and make regular commits, it is like taking notes on the process and lets you revert to a previous state in case you get stuck.
8. Use Quasar boot files for any pre-mounting app routines.
9. Be very cautious when using other libraries - Quasar can’t ensure they will be fully compatible
10. Finally, become a backer/sponsor and get access to the special Discord support chat room for priority support.

Introduction to Upgrading

While upgrading Legacy Quasar projects appears like a reasonable choice, it may not always present itself as the best solution. Just be aware that there are alternative measures that may be faster and more efficient. For instance, sometimes it is best to create a new project and port your old project. In this manner, if you do it slowly and methodologically you can see issues and resolve them quickly. This is the opposite of upgrading a project in-place, which can break everything simultaneously. Should you go with the upgrade, we have assembled the steps needed below. However, you will still need to update any Quasar components that went through a revision to get to v1.

In either case, when you build out your project as you go through this process, you may get a build error that gives no valid information and you will have no idea what might be causing it. Should this happen to you, we recommend running quasar build instead of quasar dev as the production build will sometimes give different information (from webpack) than the dev build.

If you get stuck, check out the forums and visit Discord server for help. Not just from staff, but from the community as well.

Whichever path you take, good luck!

Initial Steps

The best way to start upgrading your project is to follow these steps:

1. First, verify your current info with quasar info:

Global packages
  quasar-cli                    0.17.23

Important local packages
  quasar-cli                    0.17.23 (Quasar Framework CLI)
  quasar-framework              0.17.19 (Build responsive SPA, SSR, PWA, Hybrid Mobile Apps and Electron apps, all simultaneously using the same codebase)
  quasar-extras                 2.0.9   (Quasar Framework fonts, icons and animations)

This shows the Legacy Quasar versions (we’ll do this again at end of the steps to verify upgrade)

2. Remove local quasar-cli package

$ yarn remove quasar-cli

3. Remove folders .quasar, node_modules and package-lock.json or yarn.lock file

4. Install: quasar and @quasar/extras as dependency

$ yarn add quasar @quasar/extras

5. Install: @quasar/app as development dependency

$ yarn add --dev @quasar/app

6. Re-install all the npm packages

$ yarn

7. Babel Upgrade

Start by removing the old .babelrc and creating a new babel.config.js

Then update your babel.config.js to

module.exports = {
  presets: [
    '@quasar/babel-preset-app'
  ]
}

8. Rename the folder src/plugins to src/boot

9. In quasar.conf.js: rename the key section plugins to boot

module.exports = function (ctx) {
  return {
    // app plugins (/src/plugins)
    plugins: [
    ],

should look like this:

module.exports = function (ctx) {
  return {
    // app boot (/src/boot)
    boot: [
    ],

Do not get the Quasar plugins mixed up. Do not change this:

// Quasar plugins
framework: {
  plugins: [ // do NOT edit here
    'Notify'
  ]
}

10. In quasar.conf.js: rename the value fontawesome to fontawesome-v6, mdi to 6 and ionicons to ionicons-v4 inside the extras section, if you use them. Even if you don’t use them it is still good practice to rename them in case you do use them in the future.

11. In quasar.conf.js > framework > iconSet do same rename replacements as above to its value (fontawesome to fontawesome-v6, mdi to mdi-v6 and ionicons to ionicons-v4)

12. In quasar.conf.js: rename in framework > i18n to lang

13. In quasar.conf.js: remove all references to ctx.theme

14. Create the file quasar.variables.styl (or .sass, .scss – recommended!) in the folder ~/src/css, if does not already exist. Add the following to it (or move the contents from ~/src/css/themes/common.variables.styl):

// Quasar Stylus Variables
// --------------------------------------------------
// To customize the look and feel of this app, you can override
// the Stylus variables found in Quasar's source Stylus files.

// Check documentation for full list of Quasar variables

// It's highly recommended to change the default colors
// to match your app's branding.
// Tip: Use the "Theme Builder" on Quasar's documentation website.

$primary   = #1976d2
$secondary = #26A69A
$accent    = #9C27B0

$positive  = #21BA45
$negative  = #C10015
$info      = #31CCEC
$warning   = #F2C037

15. In the folder ~/src/css, remove the themes folder.

16. Remove the global Legacy Quasar quasar-cli and install the new @quasar/cli. (You will still be able to run legacy 0.17 projects with it)

Remove global Quasar CLI (use Yarn or NPM, depending with which you’ve installed it in the first place):

$ yarn global remove quasar-cli
# or (depending on what you've installed it with)
$ npm remove -g quasar-cli

Install global Quasar CLI

$ yarn global add @quasar/cli
# or
$ npm install -g @quasar/cli

# in ~/.bashrc or equivalent
export PATH="$(yarn global bin):$PATH"

17. Last, but not least, do a sanity check with quasar info:

Global packages
  @quasar/cli - 1.0.5

Important local packages
  quasar - 1.9.0 -- High performance, Material Design 2, full front end stack with Vue.js -- build SPA, SSR, PWA, Hybrid Mobile Apps and Electron apps, all simultaneously using the same codebase
  @quasar/app - 1.5.4 -- Quasar Framework App CLI
  @quasar/extras - 1.5.1 -- Quasar Framework fonts, icons and animations

Notice the versions that are different from step 1.

All that remains now, is fixing your pages and components for correctness. The information below can be used as a reference.

Build Themes

The iOS theme is no longer available, BUT as you will see, it’s also not necessary anymore:

• There are examples in the docs of how to make different components look and feel like iOS
• You can hook into $q.platform.is.ios to help you in setting component props differently
• The new components are very easy to customize (much easier than in Legacy Quasar)

Quasar CLI

• To create a new project use yarn create quasar or npm init quasar instead of quasar create or quasar init
• The --theme, -t option is no longer available as a build option.
• quasar describe was added for command-line help with Quasar components, etc.
• quasar inspect is a new option to see generated Webpack config.
• quasar ext is a new option for management of Quasar App Extensions.
• quasar new plugin ... is now quasar new boot ...

Build Output

The dist folder now strips out the -mat and -ios suffixes because there’s only one theme now. As a result, dist/spa-mat, dist/electron-ios, dist/pwa-mat etc now become dist/spa, dist/electron, dist/pwa.

Animation

• The JS and CSS animations were removed for v1. If you need them, you can add them manually to your quasar project by pulling them directly out of the v0.17 repository and adding them to your project.
• motion.styl
• animate.js

Misc

• this.$q.i18n was changed to this.$q.lang
• import('quasar-framework/i18n/' + lang) was changed to import('quasar/lang/' + lang) where lang would be en-us etc.
• The language pack en-uk was changed to en-gb
• this.$q.icons was changed to this.$q.iconSet
• In previous versions you would access an imported language packs isoName with:

 import('quasar/lang/' + locale).then(lang => {
   // Access the isoName with - lang.default.lang
 })

This now needs changing to

 import('quasar/lang/' + locale).then(lang => {
   // Access the isoName with - lang.default.isoName
 })

Color Palette

The colors faded, dark, light were removed. If you need those, re-add them in a new Stylus file.

// Variables
$light = #bdbdbd
$dark = #424242
$faded = #777

// CSS3 Root Variables
:root
  --q-color-light $light
  --q-color-light-d darken($light, 10%)
  --q-color-faded $faded
  --q-color-dark $dark

// CSS Classes
.text-faded
  color $faded !important
  color var(--q-color-faded) !important
.bg-faded
  background $faded !important
  background var(--q-color-faded) !important

.text-light
  color $light !important
  color var(--q-color-light) !important
.bg-light
  background $light !important
  background var(--q-color-light) !important

.text-dark
  color $dark !important
  color var(--q-color-dark) !important
.bg-dark
  background $dark !important
  background var(--q-color-dark) !important

.text-faded
  color $faded !important
  color var(--q-color-faded) !important
.bg-faded
  background $faded !important
  background var(--q-color-faded) !important

CSS

Color

• The tertiary color was renamed to accent. This applies to Brand Colors as well as Color List.

Style & Identity

Layout & Grid

Directives

• BackToTop was dropped in favor of Page Scroller.

If you are using the new QMenu component, you can alternatively use the auto-close property.

Plugins

Action Sheet

• renamed to Bottom Sheet

Local/Session Storage

The structure looks the same, but some functions have been renamed.

Components

• The components below are in alphabetical order for easier access.

QActionSheet

• was dropped in favor of BottomSheet (from code) or using a QDialog with position="bottom" (from the template).

QAlert

• replaced by QBanner
• The properties type and color are now managed by a background css class.

QAutocomplete

• removed, built into QSelect, which is far more powerfull and offers a lot more options for your autocomplete needs; make sure you get accustomed to all the features of QSelect

QBreadcrumbs

QBreadcrumbsEl

QBtn

• Type of align was changed from string to any
• Type of tabindex was changed from number to number|string

QBtnDropdown

• Type of align was changed from string to any
• Type of tabindex was changed from number to number|string

QBtnGroup

QBtnToggle

QCard

QCardTitle

• removed, use QCardSection of QCard

QCardMain

• removed, use QCardSection of QCard

QCardMedia

• removed, use QCardSection of QCard or directly place an <img> or QParallax.

QCardSeparator

• removed, use QSeparator

QCarousel

• Type of thumbnails was changed from array to boolean

QCarouselControl

• Type of offset was changed from array of 2 numbers to array

QCarouselSlide

QChatMessage

• Type of size was changed from array to string
• Type of text was changed from array to string

QCheckbox

• Type of val was changed from object to any

QChip

QChipsInput

• removed, built into QSelect

QCollapsible

• replaced by QExpansionItem

QColorPicker

• replaced by QColor
• Type of default-value was changed from string|object to string

QContextMenu

• removed, use QMenu with context-menu prop

QDatePicker

• replaced by QDate

QDatetime

• removed, use QDate and QTime

QDatetimePicker

• removed, use QDate and QTime

QDialog

QFab (Floating Action Button)

QFabAction

QField

• updated, completely new
• Do NOT use to wrap QInput or QSelect; the functionality of QField is now built into QInput and QSelect.

If you use it to wrap Input, just move all attributes from QField to QInput. If you use error and error-label, enable bottom-slots on QInput and change error-label to error-message.

QIcon

QInfiniteScroll

Replace :handler with @load.

QInnerLoading

• Type of size was changed from string|number to string

QInput

• Type of stack-label was changed from string to boolean
• Type of autofocus was changed from boolean|string to boolean

QItem

QItemMain

• removed, use QItemLabel

QItemSeparator

• replaced by QSeparator

QItemSide

• removed, use QItemSection

QItemTile

• removed, use QItemSection
• QItemTile with label property, use QItemLabel with header property
• QItemTile with sublabel property, use QItemLabel with caption property

QJumbotron

• removed, use QCard

QKnob

QLayout

QLayoutDrawer

• renamed to QDrawer

QLayoutHeader & QLayoutFooter

• renamed to QHeader and QFooter, respectively

QList

QListHeader

• removed, use QItemLabel with header property

QModal

• removed, use QDialog

QModalLayout

• removed, use QDialog with a QLayout (and its container prop)

QOptionGroup

QPagination

QParallax

QPopover

• replaced by QMenu
• Type of anchor was changed from object to string
• Type of self was changed from object to string
• Type of offset was changed from array of 2 numbers to array

QPopupEdit

QProgress

• replaced by QLinearProgress (alternatively, use QCircularProgress)

QPullToRefresh

QRadio

QRange

QRating

• Type of max was changed from number to string|number

QResizeObservable

• renamed to QResizeObserver

QRouteTab

• Type of name was changed from string to string|number
• Type of alert was changed from boolean to boolean|string
• Type of label was changed from string to string|number
• Type of to was changed from string|object to any
• Do not use slot="title" on it anymore

QScrollArea

• Type of delay was changed from number to string|number

QScrollObservable

• renamed to QScrollObserver

QSearch

• removed, use QInput with debounce property (and optionally some icons on append or prepend slots)

QSelect

• Type of stack-label was changed from string to boolean
• Type of display-value was changed from string to string|number
• When the option list is an array of objects (as opposed to simple strings or numbers), upgraders may want to turn on the emit-value and map-options flags to preserve the behavior of previous versions. 1.0 defaults to emitting the entire object, not just the value property, upon selection.

QSlider

QSpinnerMat

• removed, use QSpinner

QStep

• Type of name was changed from string|number to any

QStepper

• Type of done-icon was changed from boolean to string
• Type of active-icon was changed from boolean to string
• Type of error-icon was changed from boolean to string

QTab

• Type of name was changed from string to string|number
• Type of alert was changed from boolean to boolean|string
• Type of label was changed from string to string|number
• Type of tabindex was changed from number to string
• Do not use slot="title" on it anymore

QTable

filter - type changed from String to String,Object

QTableColumns

• removed, use a QSelect with columns as options (see docs for example)

QTabPane

• removed, use QTabPanels and QTabPanel (outside of a QTabs)

QTabs

Remove slot="title" from all tabs. It’s not needed anymore. If you use QTabs with QTabPanes, remove them from the QTab container and put them into separate QTabPanel container. Put v-model on both containers and point it to the same variable. If you have default on some tab, put its name as default value of the model.

QTimeline

QTimelineEntry

QTimePicker

• replaced by QTime

QTime Properties

QToggle

• Type of val was changed from object to any
• checked-icon and indeterminate-icon were dropped to make QCheckbox more compliant with Material Standards. If you still need similar functionality, consider using QToggle with icons.

QToolbar

QTooltip

QTree

QUploader

• Type of headers was changed from object to function|array
• Type of url was changed from string to function|string
• Type of method was changed from string to function|string

QWindowResizeObservable

• removed, directly use this.$q.screen.width and this.$q.screen.height (or create a watcher on them)