Migrating from v1.5.x to v2.0.x

Version 2 contains non backwards compatible breaking changes. This includes previously deprecated functionality from v1.x.x. These breaking changes are noted in the console for the corresponding components.

The existing grid is still operational and has an eslint plugin to help with migration. This plugin can also be used to help upgrade to the new grid.

Bootstrap

Vuetify must now be instantiated and passed to the initial Vue instance. This is similar to how vue-router and vuex are bootstrapped.

Vue-CLI 3 Vuetify plugin install

// v1.5
// src/plugins/vuetify.js

import Vue from 'vue'
import Vuetify from 'vuetify/lib'
import 'vuetify/src/stylus/app.styl'

Vue.use(Vuetify, {
  iconfont: 'md',
})

// src/main.js
import Vue from 'vue'
import './plugins/vuetify'
import App from './App.vue'

Vue.config.productionTip = false

new Vue({
  render: h => h(App),
}).$mount('#app')

// v2.0
// src/plugins/vuetify.js

import Vue from 'vue';
import Vuetify from 'vuetify/lib';

Vue.use(Vuetify);

export default new Vuetify({
  icons: {
    iconfont: 'mdi',
  },
});

// src/main.js
import Vue from 'vue'
import App from './App.vue'
import vuetify from './plugins/vuetify';

Vue.config.productionTip = false

new Vue({
  vuetify,
  render: h => h(App)
}).$mount('#app')

Full Install

// v1.5

import Vue from 'vue'
import Vuetify from 'vuetify'
import 'vuetify/src/stylus/main.styl'

const opts = { ... }
Vue.use(Vuetify, opts)

new Vue(...).$mount('#app')

// v2.0

import Vue from 'vue'
import Vuetify from 'vuetify'
import 'vuetify/dist/vuetify.min.css'

const opts = { ... }
Vue.use(Vuetify)

new Vue({
  vuetify: new Vuetify(opts)
}).$mount('#app')

A-La-Carte Install (vuetify-loader)

// v1.5

import Vue from 'vue'
import Vuetify from 'vuetify/lib'
import 'vuetify/src/stylus/main.styl'

const opts = { ... }
Vue.use(Vuetify, opts)

new Vue(...).$mount('#app')

// v2.0

import Vue from 'vue'
import Vuetify from 'vuetify/lib'

const opts = { ... }
Vue.use(Vuetify)

new Vue({
  vuetify: new Vuetify(opts)
}).$mount('#app')

Framework

The following components are now lazy by default. This means they will not render their content until they are explicitly activated. This drastically improves performance but may not be wanted depending upon your application's needs (i.e. For SEO purposes). To return to the previous behavior, use the eager prop.

v-badge
v-menu
v-tooltip
v-dialog
v-bottom-sheet

vuetify/lib is now compiled to es6. This means supporting IE requires transpileDependencies or similar to be used, along with @babel/polyfill. Transpile dependencies are automatically added when using vue-cli-3. If you have an older version, you can simple add 'vuetify' to the list.

Theme

Now supports dark/light theme variants. The dark property has been moved into the theme property. Will dynamically change when toggling $vuetify.theme.dark. If only using one variant, you only need to define its colors.

// v1.5

const opts = {
  dark: true,
  theme: {
    primary: '...',
    ...
  }
}

// v2.0

const opts = {
  theme: {
    dark: true,
    themes: {
      light: {
        primary: '...',
        ...
      },
      dark: {
        primary: '...',
        ...
      }
    }
  }
}

In order to disable the theme style sheet creation, you must use the disable property of the theme object.

// v1.5

const opts = {
  theme: false
}

// v2.0
const opts = {
  theme: { disable: true }
}

Icons

Icon and iconfont declaration is now scoped under the icons property.

// v1.5

const opts = {
  iconfont: 'fa4',
  icons: { ... }
}

// v2.0

const opts = {
  icons: {
    iconfont: 'fa4',
    values: { ... }
  }
}

Now defaults to use mdi icons. For information on how to install please navigate here
Is now located under the icons property of the Vuetify options

If you want to use a custom iconfont, you must set it up in the initial Vuetify options now.

// v1.5

import Vue from 'vue'
import Vuetify from 'vuetify'

Vue.use(Vuetify, {
  iconfont: 'fa4'
})

// v2.0

import Vue from 'vue'
import Vuetify from 'vuetify'

Vue.use(Vuetify, {
  icons: {
    iconfont: 'fa4'
  }
})

Goto (scrolling helper)

Import location has changed. Must be explicitly bootstrapped with the Vuetify instance to use in vue-router scroll-behavior. Example of how to do this here. Reference documentation for scroll-behavior usage here.

// v1.5

import goTo from 'vuetify/es5/components/Vuetify/goTo'

// v2.0

import goTo from 'vuetify/lib/services/goto'

Lang

The translator function t is now nested under the lang property.

// v1.5

this.$vuetify.t(...)

// v2.0

this.$vuetify.lang.t(...)

Grid

The grid has been rebuilt modeled after bootstrap. The existing grid still works and needs some slight modifications. Kael has created an eslint plugin to help with this process.

eslint-plugin-vuetify to fix most of these for you
Spacing helpers have changed to represent the number of 4px intervals from 0-12 (0-48px)
- eg. px-7 is 7 * 4 = 28px
- 3 → 4
- 4 → 6
- 5 → 12
Most "breakpointed" and "non-breakpointed" helpers have been normalised, eg. .text-xs-center is now text-center as it applies to all screen widths unless overridden
Children of .d-flex no longer have extra flex rules applied. This can be done manually with .flex-grow-1
Helper classes changed:
- .fluid → .container--fluid
- .scroll-y → .overflow-y-auto
- .hide-overflow → .overflow-hidden
- .show-overflow → .overflow-visible
- .no-wrap → .text-no-wrap
- .ellipsis → .text-truncate
- .left → .float-left
- .right → .float-right
<v-layout row> should not be used as .row is now part of the new grid instead (#7956)

Use the following regex to update spacing classes:

find: ([\s"][mp][axytblr])-5
replace: $1-12

find: ([\s"][mp][axytblr])-4
replace: $1-6

find: ([\s"][mp][axytblr])-3
replace: $1-4

For examples on how the v2 grid compares to v1.5, check out this github gist.

Styles

The main framework styles are now imported automatically.

// v1.5
// src/plugins/vuetify.js

import 'vuetify/src/styles/main.sass' // can be removed

Must install the sass package

yarn add sass -D
// OR
npm install sass -D

Do not install node-sass, it is not the correct library.

Typography

The root font-size (per MD2 specification) is now 16px.

The following typography classes have been replaced:
- subheading → subtitle-1

Event names

All event names has been changed from camelCase to kebab-case:

update:searchInput → update:search-input
update:inputValue → update:input-value
update:miniVariant → update:mini-variant
update:pickerDate → update:picker-date
update:selectingYear → update:selecting-year
tableDate → update:table-date
update:returnValue → update:return-value

Activators

Components with activators, v-tooltip, v-menu, v-dialog, v-list-group and v-bottom-sheet must now be bound using the new v-slot syntax
- Requires Vue@2.6
We understand this is considerably more verbose than the v1.5 counterpart. We are still exploring ways to support the new v-slot in a more concise manner
- You can find more information on the official Vue documentation for Destructuring Slot Props
- You can find more information on the official Vue documentation for v-slot
The upside to this change is it is easier to support nested activators and provide proper a11y support

Regular activator

<!-- v1.5 -->

<v-dialog>
  <v-btn slot="activator">...</v-btn>
</v-dialog>

<!-- v2.0 -->

<v-dialog>
  <template v-slot:activator="{ on }">
    <v-btn v-on="on">...</v-btn>
  </template>
</v-dialog>

Nested activator

<!-- v2.0 -->

<v-menu>
  <template v-slot:activator="{ on: menu }">
    <v-tooltip bottom>
      <template v-slot:activator="{ on: tooltip }">
        <v-btn
          color="primary"
          dark
          v-on="{ ...tooltip, ...menu }"
        >
          Dropdown w/ Tooltip
        </v-btn>
      </template>
      <span>Im A ToolTip</span>
    </v-tooltip>
  </template>
</v-menu>

Unit tests

Testing with Vuetify is now similar to that of vue-router and vuex.

// setup.js

import Vue from 'vue'
import Vuetify from 'vuetify'

Vue.use(Vuetify)

// Component.spec.js

import { createLocalVue, mount } from '@vue/test-utils'
import Vuetify from 'vuetify'
import Component from 'path/to/my/component'

const localVue = createLocalVue()

describe('Component.vue', () => {
  let vuetify

  beforeEach(() => {
    vuetify = new Vuetify(...)
  })

  it('should...', () => {
    const wrapper = mount(Component, {
      localVue,
      vuetify
    })
  })
})

Form Input Validation

All form inputs default to white when using the dark prop unless the application is explicitly set to dark mode.

Removed Component Properties

These are previous deprecations from earlier versions that have now been removed:

<v-text-field textarea> will no longer render <v-textarea>
<v-select autocomplete> will no longer render <v-autocomplete>
<v-select combobox> will no longer render <v-combobox>
<v-select overflow> will no longer render <v-overflow-btn>
<v-select segmented> will no longer render <v-overflow-btn segmented>
<v-select editable> will no longer render <v-overflow-btn editable>

Individual Components

These are the changes required for existing components.

`v-app`

Component classes have been prepended with v-. eg .application → .v-application
The dark and light prop no longer have an effect on application theme variants

<!-- v1.5 src/App.vue -->

<template>
  <v-app dark>
    ...
  </v-app>
</template>

// v2.0 src/plugins/vuetify.js

import Vue from 'vue'
import Vuetify from 'vuetify'

Vue.use(Vuetify)

export default new Vuetify({
  theme: { dark: true }
})

`v-alert`

Alerts are visible by default

<!-- v1.5 -->

<template>
  <v-alert :value="true">
    ...
  </v-alert>
</template>

<!-- v2.0 -->

<template>
  <v-alert>
    ...
  </v-alert>
</template>

`v-carousel`

The cycle prop is no longer implicit, must be defined in order to have screens switch

`v-btn`

The flat prop is now text
The round prop is now rounded
No longer has explicit margin

`v-chip`

value no longer controls visibility, use active
input event emitted when clicking
The close event is now click:close
@input listener is now @active.sync

<!-- v1.5 -->

<v-chip :value="chip" @input="chip = $event">...</v-chip>
<v-chip v-model="chip">...</v-chip>

<!-- v2.0 -->

<v-chip :active="chip" @update:active="chip = $event">...</v-chip>
<v-chip :active.sync="active">...</v-chip>

`v-bottom-nav`

Renamed from v-bottom-nav to v-bottom-navigation

`v-bottom-navigation`

The color prop is now background-color
The color prop now affects the active <v-btn> color

`v-bottom-sheet-transition`

Component has been removed

Developer notes: Was never explicitly listed in API

`v-btn`

The flat prop is now text
The round prop is now rounded
No longer has explicit margin

`v-card-media`

Component has been removed

`v-carousel`

The cycle prop is no longer implicit, must be defined in order to have screens switch

`v-chip`

The value prop is now active
value no longer controls visibility. input event emitted when clicking
The selected prop is now input-value or v-model
The close event is now click:close

`v-data-iterator` & `v-data-table`

Data table (and iterator) have been rewritten from the ground up to be both easier to use and to allow for more flexibilty in more advanced use cases. This has resulted in a number of breaking changes. Some of these are shared between both components while some are unique to each.

Shared

disable-initial-sort has been removed. Neither component initially sorts data anymore. Use sort-by (or options) prop to sort
filter prop has been removed. Instead use custom-filter. This was done in an effort to make custom filtering less confusing
- The signature for custom-filter has changed from (items: object[], search: string, filter: Filter): object[] to (value: any, search: string, item: any) => boolean
pagination prop has been removed. Instead use the separate props such as page, sort-by, etc. If you want to provide a single object you can use the new options prop instead. NOTE: The options prop has a different object structure than pagination. Check API docs for details
total-items prop has been renamed to server-items-length
hide-actions prop has been renamed to hide-default-footer. Also it no longer changes the visible items per page
Props related to the default footer have been move to the footer-props prop. These are:
- prev-icon
- next-icon
- rows-per-page-items → items-per-page-options
- rows-per-page-text → items-per-page-text
The expand prop has been removed

`v-data-iterator`

The content-tag, content-props, content-class props have been removed. Instead simply use the default scoped slot to implement your intended markup.

`v-data-table`

items slot has been renamed to item
headers slot renamed to header
item slot (and header) now require you to define a <tr> element. Previously this was optional
expand slot renamed to expanded-item. It no longer includes an expansion transition, and the slot is inside the <tr> element so that you can define your own <td> columns. To get back to a similar look as in 1.5, you will need a <td> with colspan equal to the number of columns in your header
hide-header has been renamed to hide-default-header
select-all has been renamed to show-select. This will also render a checkbox on each item row as long as you are not defining a slot that overrides the internal row rendering (such as item or body)
Props related to the default header have been moved to the header-props prop. These are:
- sort-icon

`v-expansion-panel` et al

Many components have been renamed and props moved
- v-expansion-panel → v-expansion-panels
- v-expansion-panel-content → v-expansion-panel
New components
- v-expansion-panel-header
- v-expansion-panel-content

<!-- v1.5 -->

<v-expansion-panel>
  <v-expansion-panel-content
    v-for="(item,i) in 5"
    :key="i"
  >
    <template v-slot:header>Item</template>
    <v-card>
      ...
    </v-card>
  </v-expansion-panel-content>
</v-expansion-panel>

<!-- v2.0 -->

<v-expansion-panels>
  <v-expansion-panel
    v-for="(item,i) in 5"
    :key="i"
  >
    <v-expansion-panel-header>
      Item
    </v-expansion-panel-header>
    <v-expansion-panel-content>
      <v-card>
        ...
      </v-card>
    </v-expansion-panel-content>
  </v-expansion-panel>
</v-expansion-panels>

`v-footer`

Now has explicit padding to match other similar MD components. Can be removed with the padless prop or a helper class, class="pa-0"

`v-jumbotron`

Component has been removed

`v-list` et al

Many components have been renamed
- v-list-tile → v-list-item
- v-list-tile-action → v-list-item-action
- v-list-tile-avatar → v-list-item-avatar
- v-list-tile-content → v-list-item-content
- v-list-tile-title → v-list-item-title
- v-list-tile-sub-title → v-list-item-subtitle
- The avatar prop has been removed

`v-list-group`

Can no longer use v-list-items in the activator slot
- listeners are passed through to the internal v-list-item for activators
- use v-list-item-content/v-list-item-title etc instead

`v-navigation-drawer`

Default width has been changed from 300px to 256px. You can adjust it using width prop.

`v-select`, `v-autocomplete`, `v-combobox`, `v-overflow-btn`

Now passes attributes and listeners to item slot for proper a11y support (split from tile to match other implementations).

<!-- v1.5 -->

<v-select>
  <template v-slot:item="{ item, tile }">
    <v-list-tile v-bind="tile">
       ...
    </v-list-tile>
  </template>
</v-select>

<!-- v2.0 -->

<v-select>
  <template v-slot:item="{ item, attrs, on }">
    <v-list-item v-bind="attrs" v-on="on">
       ...
    </v-list-item>
  </template>
</v-select>

The item scoped slot value of { tile } is now { attrs, on }. is now bound similar to the v-menu activator slot.

`v-select`

No longer has a default autocomplete of on

`v-speed-dial`

Icons no longer have inferred swapping for activator through css
The activator slot will provide a model in the future

<!-- v1.5 -->

<v-speed-dial>
  <template v-slot:activator>
    <v-btn
      dark
      fab
    >
      <v-icon>account_circle</v-icon>
      <v-icon>close</v-icon>
   </v-btn>
  </template>
</v-speed-dial>

<!-- v2.0 -->

<v-speed-dial v-model="fab">
  <template v-slot:activator>
    <v-btn
      dark
      fab
    >
      <v-icon v-if="fab">account_circle</v-icon>
      <v-icon v-else>close</v-icon>
    </v-btn>
  </template>
</v-speed-dial>

`v-tabs`

The color prop is now background-color. Color now affects the default text and slider color
Various class names have been changed throughout
- v-tab__div removed, use v-tab
- v-tab__item → v-tab
- v-tabs__slider → v-tabs-slider
- v-tabs__bar → v-tabs-bar

`v-tabs-items`

No longer implicitly inherits the v-tabs model when nested. Must have :value or v-model explicitly bound.

<!-- v1.5 -->

<v-tabs v-model="tabs">
  ...
  <v-tabs-items>
    ...
  </v-tabs-items>
</vtabs>

<!-- v2.0 -->

<v-tabs v-model="tabs">
  ...
  <v-tabs-items v-model="tabs">
    ...
  </v-tabs-items>
</vtabs>

Developer notes: The tabs-items component does not have to be provided and is only necessary for custom implementations.

`v-text-field`

The mask prop and functionality has been removed. Instead you can use 3rd party libraries such as vue-the-mask.

`v-text-field`, `v-select`, `v-textarea`, `v-autocomplete`, `v-combobox`

The box prop is now filled

<!-- v1.5 -->

<v-text-field box></v-text-field>

<!-- v2.0 -->

<v-text-field filled></v-text-field>

`v-text-field`, `v-select`, `v-textarea`, `v-autocomplete`, `v-combobox`, `v-btn`, `v-alert`

The outline prop is now outlined

<!-- v1.5 -->

<v-btn outline></v-text-field>
<v-autocomplete outline></v-autocomplete>
<v-alert outline></v-alert>

<!-- v2.0 -->

<v-btn outlined></v-text-field>
<v-autocomplete outlined></v-autocomplete>
<v-alert outlined></v-alert>

`v-toolbar`

All existing scrolling techniques and app functionality has been deprecated and moved to v-app-bar

🆘 I need help!

If you are stuck and need help, don't fret! We have a very large and dedicated community that is able to provide help 24/7. Come to the #release-migration channel.

Files

MIGRATION.md

Latest commit

History

MIGRATION.md

File metadata and controls

Migrating from v1.5.x to v2.0.x

Bootstrap

Vue-CLI 3 Vuetify plugin install

Full Install

A-La-Carte Install (vuetify-loader)

Framework

Theme

Icons

Goto (scrolling helper)

Lang

Grid

Styles

Typography

Event names

Activators

Regular activator

Nested activator

Unit tests

Form Input Validation

Removed Component Properties

Individual Components

v-app

v-alert

v-carousel

v-btn

v-chip

v-bottom-nav

v-bottom-navigation

v-bottom-sheet-transition

v-btn

v-card-media

v-carousel

v-chip

v-data-iterator & v-data-table

Shared

v-data-iterator

v-data-table

v-expansion-panel et al

v-footer

v-jumbotron

v-list et al

v-list-group

v-navigation-drawer

v-select, v-autocomplete, v-combobox, v-overflow-btn

v-select

v-speed-dial

v-tabs

v-tabs-items

v-text-field

v-text-field, v-select, v-textarea, v-autocomplete, v-combobox

v-text-field, v-select, v-textarea, v-autocomplete, v-combobox, v-btn, v-alert

v-toolbar

🆘 I need help!

`v-app`

`v-alert`

`v-carousel`

`v-btn`

`v-chip`

`v-bottom-nav`

`v-bottom-navigation`

`v-bottom-sheet-transition`

`v-btn`

`v-card-media`

`v-carousel`

`v-chip`

`v-data-iterator` & `v-data-table`

`v-data-iterator`

`v-data-table`

`v-expansion-panel` et al

`v-footer`

`v-jumbotron`

`v-list` et al

`v-list-group`

`v-navigation-drawer`

`v-select`, `v-autocomplete`, `v-combobox`, `v-overflow-btn`

`v-select`

`v-speed-dial`

`v-tabs`

`v-tabs-items`

`v-text-field`

`v-text-field`, `v-select`, `v-textarea`, `v-autocomplete`, `v-combobox`

`v-text-field`, `v-select`, `v-textarea`, `v-autocomplete`, `v-combobox`, `v-btn`, `v-alert`

`v-toolbar`