Diagnosing Framework7 Vue Components That Render but Never Update

The recognizable condition

Your Framework7 Vue page mounts without errors. The navbar, list, and buttons all appear. But when state changes — a toggle flips, a list reloads, a route parameter updates — the UI stays frozen on its initial values. No console error, no crash, just a silent no-op. This is one of the most common Framework7 + Vue failure modes, and it almost always comes down to one of four causes: non-reactive data, a version mismatch between the core and Vue packages, conditional rendering that destroys component state, or a list missing stable keys.

This guide walks through the checks in order of likelihood. Each check has a concrete fix, and the last section covers when to stop debugging locally and escalate.

Cause and diagnostic table

Check 1: Confirm the data is actually reactive

Vue can only track properties that exist when the component is created. If you add a property later — for example, assigning this.filter = 'all' inside a method without declaring it first — the template reads it once (or as undefined) and never updates.

Open Vue devtools, select the page component, and look at its reactive state. If the property your template binds to is missing from that list, it was never declared. The fix is to declare every template-referenced property in data():

export default {
  data() {
    return {
      filter: 'all',
      items: [],
      loading: false,
    };
  },
};

With the Composition API, the equivalent check is that every template binding is a ref or reactive value returned from setup() — a plain let variable will render once and never update.

Check 2: Rule out a version mismatch

Framework7's Vue components are a separate package (framework7-vue) that must match the core framework7 major version. A mismatch typically doesn't throw — components register but hooks and reactivity glue silently misbehave. In your project root, run:

npm ls framework7 framework7-vue

This requires no special permissions and changes nothing. Both packages should report the same major and minor version (for example, both on 8.x). If they diverge, align them:

npm install framework7@8 framework7-vue@8

Pin exact versions in package.json afterward — a caret range on one package and a pinned version on the other is how these mismatches usually creep in. Also check the browser console during startup for framework7 is not defined or registration warnings, which indicate the plugin was never installed with app.use() or the Framework7 Vue plugin registration call.

Check 3: Audit v-if blocks for listener leaks

v-if fully destroys and recreates the subtree. If a component inside a v-if block attaches Framework7 event handlers — say, $$('.popup').on('opened', ...) or a Dom7 listener in mounted() — and doesn't remove them in unmounted(), every toggle adds another listener. The visible symptom is handlers firing multiple times, or state updates appearing to "lag" by one toggle.

The fix has two parts. First, pair every subscription with cleanup:

mounted() {
  this.onPopupOpen = () => { this.loading = true; };
  this.$$('.popup').on('popup:opened', this.onPopupOpen);
},
unmounted() {
  this.$$('.popup').off('popup:opened', this.onPopupOpen);
}

Second, if the subtree is toggled frequently and holds expensive state, prefer v-show, which toggles CSS visibility instead of destroying the DOM. The tradeoff: v-show keeps the component alive, so anything it fetches or listens to stays active even when hidden.

Check 4: Fix list rendering with stable keys

Framework7's f7-list with v-for needs a stable, unique :key per row. Using the array index as the key works until you reorder, insert, or delete — then Vue reuses the wrong DOM nodes and rows show stale content.

<f7-list>
  <f7-list-item
    v-for="item in items"
    :key="item.id"
    :title="item.name"
  />
</f7-list>

To verify, reorder the array in devtools (items.reverse() on the component state) and confirm each DOM row moves with its data rather than keeping its position with new text. If rows keep position but swap content, the key is the problem.

Check 5: Platform-specific rendering

Framework7 applies iOS or Material Design styling based on the detected theme, adding an ios or md class to the root element. Conditional markup that assumes one theme — for example, an iOS-only navbar structure — will render incorrectly on Android. Inspect the root element in devtools to confirm which theme class is active, and gate platform-specific markup on Framework7's theme detection rather than your own user-agent sniffing. Test both themes by forcing the theme in the app initialization options during development.

Verifying the fix

After applying a fix, confirm the behavior end to end: change the state through the real UI path (not just devtools), watch the DOM update in the Elements panel, and check the console stays clean across several toggles. For the listener-leak fix specifically, toggle the v-if block five or six times and confirm each action fires exactly once.

When to escalate

Stop debugging locally and escalate — to a maintainer issue or a deeper profiling session — when: versions match and data is reactive but updates still stall (possible upstream bug; reproduce in a minimal single-component project first); memory grows even with cleanup paired correctly (profile with heap snapshots rather than guessing); or the failure only appears inside page transitions, which points at router configuration rather than the component. A minimal reproduction — one page, one component, one state property — is the single most useful artifact you can attach to an escalation.