Migration to Framework7 v5

Framework7 stable 5.0.0 released on October 7, 2019 and it is time to update!

Let's walk through all v3 -> v4 breaking changes to see what needs to be changed to upgrade your app to new Framework7 v4.

In this article we will walk most of v4 -> v5 breaking changes to check what needs to be done to migrate from Framework7 v4 to Framework7 v5.

But first of all it is recommended to read **what is new in v5** and check **full v5 changelog** for full list of changes that can be used as a good reference.

Framework7 Core

New Responsive Breakpoints

Framework7 uses new responsive breakpoints to apply different styles based on app width.

They are now:

  • xsmall - width more than 480px
  • small - width more than 568px
  • medium - width more than 768px
  • large - width more than 1024px
  • xlarge - width more than 1200px

If you use tablet-${n} and desktop-${n} modifiers classes on Layout Grid columns:

<div class="col-50 tablet-33 desktop-25">...</div>

they must be changed to the following:

<div class="col-50 medium-33 large-25">...</div>

Same for Lists and Block, if you use tablet-inset class there, it must be changed to medium-inset

<div class="list tablet-inset">...</div>
<div class="tablet-inset block">...</div>

should be changed to:

<div class="list medium-inset">...</div>
<div class="medium-inset block">...</div>

New Side Panels APIs

Panels functionality has been fully reworked and now they behave more like a modals.

Global app panel parameters (like panel.swipe = 'left' ) are not supported anymore and now every panel must be initialized separately and panel parameters must be specified for each panel. And to make transition easier it is possible to auto init the Panel by adding panel-init class and specify panel parameters with data- attributes.

For example, if we have something like this in v4:

<div id="app">
  <div class="panel panel-left panel-reveal">...</div>
  <div class="panel panel-right panel-cover">...</div>
</div>
<script>
  var app = new Framework7({
    panel: {
      // make left panel swipeable
      swipe: 'left',
      // breakpoint when left panel becomes visible
      leftBreakpoint: 768,
      // breakpoint when right panel becomes visible
      rightBreakpoint: 1024,
    },
  });
</script>

It must be changed to the following in v5:

<div id="app">
  <!--
  * new "panel-init" class to auto init the panel
  * swipe and visibleBreakpoint passed as data- attributes
  -->
  <div
    class="panel panel-left panel-reveal panel-init"
    data-swipe="true"
    data-visible-breakpoint="768"
  >
    ...
  </div>
  <div
    class="panel panel-right panel-cover panel-init"
    data-visible-breakpoint="1024"
  >
    ...
  </div>
</div>
<script>
  var app = new Framework7({
    // no any panel related params here
  });
</script>

Check updated Panel Docs for all new APIs and examples.

New Navbar Layout

In v5 Navbar container must have new navbar-bg element that should be placed before navbar-inner, and new layout looks like:

<div class="navbar">
  <!-- new required navbar-bg element -->
  <div class="navbar-bg"></div>

  <div class="navbar-inner">
    <!-- ... -->
  </div>
</div>

Large Navbar (Navbar with large title) now should be enabled by adding navbar-large class to Navbar element:

<!-- new navbar-large class for navbar with large title -->
<div class="navbar navbar-large">
  <div class="navbar-bg"></div>
  <div class="navbar-inner">
    <!-- ... -->
    <div class="title-large">...</div>
  </div>
</div>

New Calendar API

Now Calendar uses ECMAScript Internationalization API, specifically Intl.DateTimeFormat (for date/time format, month names, day names, etc.).

It has new Month and Year pickers which are enabled by default. Check updated Calendar Docs for new APIs.

Fast Clicks Removed

Fast clicks functionality has been completely removed. Following app parameters are not supported anymore: touch.fastClicks, touch.fastClicksDistanceThreshold, touch.fastClicksDelayBetweenClicks and touch.fastClicksExclude

Request.Promise

Now it resolves and rejects with a different object.

  • will be resolved with { data, status, xhr } object (rather than with just data like before)
  • Request "promise" methods now will be rejected with { message, status, xhr } object (rather than with just status like before)
// In v4 we had
app.request.promise(...)
  .then((data) => {
    console.log(`Response data is: ${data}`)
  })
  .catch((status) => {
    console.log(status);
  })

// In v5 it is

app.request.promise(...)
  .then((res) => {
    console.log(`Response data is: ${res.data}`)
    console.log(`Response status is: ${res.status}`)
  })
  .catch((err) => {
    console.log(err.status);
    console.log(err.message);
  })

// or
app.request.promise(...)
  .then(({ data, xhr, status }) => {
    console.log(`Response data is: ${data}`)
    console.log(`Response status is: ${status}`)
  })
  .catch(({ xhr, status, message }) => {
    console.log(status);
    console.log(message);
  })

Router Component

Component DOM updates are now asynchronous. It means that it is not guaranteed that DOM will be updated right after calling $setState. There is a new $tick method that can be safely used to reference DOM and ensure it was updated. Or we can now use new second callback argument in $setState

this.$setState({ foo: 'bar' });
this.$setState({ john: 'doe' });
this.$tick(() => {
  // DOM updated
});

// Or with callback
this.$setState({ foo: 'bar' }, () => {
  // DOM updated
});

// or with promise
this.$setState({ foo: 'bar' }).then(() => {
  // DOM updated
});

Framework7 Vue & React

Framework7 Lite

It is new "Lite" version of Framework7 Core that doesn't contain Core Component functionality. And now it is recommended to use "lite" version with F7-Vue/React packages:

import Framework7 from 'framework7/framework7-lite.esm.js';

or bundle version:

import Framework7 from 'framework7/framework7-lite.esm.bundle.js';

List & Block Components

tabletInset prop has been removed, and new props based on new responsive breakpoints should be used instead: xsmallInset, smallInset, mediumInset, largeInset, xlargeInset

<List mediumInset>...</List>
<Block mediumInset>...</Block>

and

<f7-list mediumInset>...</f7-list> <f7-block mediumInset>...</f7-block>

Col Component

tabletWidth and desktopWidth props have been removed, and new props based on new responsive breakpoints should be used instead: xsmall, small, medium, large, xlarge :

<Col size="50" medium="33" large="25">
  ...
</Col>

and

<f7-col size="50" medium="33" large="25">...</f7-col>

Panel Component

Panels got new API, so main app parameters related to Panel are not actual anymore and all panel parameters should be defined on Panel itself:

<App>
  <Panel left cover swipe visibleBreakpoint={768}>
    ...
  </Panel>
  <Panel right cover visibleBreakpoint={1024}>
    ...
  </Panel>
  ...
</App>

<f7-app>
  <f7-panel left cover swipe :visible-breakpoint="768">...</f7-panel>
  <f7-panel right cover :visible-breakpoint="1024">...</f7-panel>
  ...
</f7-app>

Statusbar Component

Statusbar component has been removed as its logic was reworked. So make sure you are not referring Statusbar / f7-statusbar components in app.

New Framework7 Icons

Framework7 Icons icon font was also updated to new version 3 with more than 800 new icons. As it is now based on Apple's SF Symbols, most of icon names were renamed. Check the Framework7 Icons Cheatsheet - for new v3 icons. And you can still access old (v2) cheatsheet (for comparison) by downloading latest 2.x icons release from repository releases https://github.com/framework7io/framework7-icons/releases

That Is All

There is not so much breaking changes in v5, but there are a lot of new features. Check **what is new in v5** blog post if you missed it.

As next steps it is highly recommended to check all new Framework7 v5 docs and:

P.S.

If you love Framework7, please, support project by donating or pledging on Patreon: https://www.patreon.com/framework7

Your support means a lot for us!