Framework7 Vue

Common errors

• Failed to resolve component: f7-app

  cause The Framework7 Vue plugin (`Framework7Vue`) was not correctly installed or registered with the Vue application.
  fix Ensure you have `import Framework7 from 'framework7/lite-bundle'; import Framework7Vue from 'framework7-vue'; Framework7.use(Framework7Vue);` (or `app.use(Framework7Vue)`) in your application's entry file before mounting the Vue app.

• TypeError: Cannot read properties of undefined (reading 'dialog') (or similar error when accessing `this.$f7` or `f7`)

  cause Attempting to access the Framework7 instance (`this.$f7` or the `f7` export) before Framework7 has fully initialized or before it's available within the component context.
  fix Use the `f7ready` utility function or the `this.$f7ready()` component method to ensure Framework7 is initialized before interacting with its APIs. For example, `this.$f7ready((f7Instance) => { f7Instance.dialog.alert('Hello!'); });`.

• TS2307: Cannot find module 'framework7/framework7-bundle.min.css' or its corresponding type declarations.

  cause TypeScript is unable to resolve the imported CSS module, often because there's no declaration file for `.css` imports or the `framework7` types are missing.
  fix Ensure you have installed `@types/framework7` (`npm install -D @types/framework7`) and that your `tsconfig.json` includes `"allowSyntheticDefaultImports": true` and a `css.d.ts` file or similar declaration to handle CSS module imports (e.g., `declare module '*.css';`).

Warnings

• breaking The `dynamicNavbar` functionality has been completely removed from Navbar components.
  Fix: Review your application's `f7-navbar` implementations. If you relied on `dynamicNavbar`, you will need to refactor your navigation structure to explicitly define unique navbars for each page or use other dynamic rendering techniques. There is no direct replacement for this specific functionality.
• breaking The default 'Back' link text in navbars has been changed to an icon-only approach, removing the explicit 'Back' text by default.
  Fix: If your application relies on the visible 'Back' text, you must explicitly set the `back-link` prop to your desired text, for example, `<f7-navbar title="Page Title" back-link="Back"></f7-navbar>`.
• gotcha Framework7 CSS/theme files must be imported separately from the `framework7` package, not `framework7-vue`.
  Fix: Ensure you import the correct CSS file, typically `import 'framework7/framework7-bundle.min.css';` or specific theme files like `framework7/framework7-ios.min.css` in your entry point (e.g., `main.js/ts`). Missing these imports will result in unstyled components.

Install

• npm install framework7-vue npm
• yarn add framework7-vue yarn
• pnpm add framework7-vue pnpm

Imports

• Framework7Vue
  wrong:

  import { Framework7Vue } from 'framework7-vue';

  correct:

  import Framework7Vue from 'framework7-vue';

  This is the default export representing the Vue plugin, which you pass to `app.use()` to register all Framework7 components and features with your Vue application.
• f7
  wrong:

  import Framework7 from 'framework7-vue'; const f7Instance = Framework7.instance;

  correct:

  import { f7 } from 'framework7-vue';

  The `f7` named export provides direct access to the global Framework7 core instance for programmatic API calls (e.g., dialogs, router). Within Vue components, `this.$f7` or `useFramework7()` (Composition API) is often preferred.
• f7ready

  import { f7ready } from 'framework7-vue';

  This utility function allows you to execute code once Framework7's core instance is fully initialized, which is crucial for interacting with its APIs reliably, especially outside Vue component lifecycle hooks.
• Framework7 core CSS
  wrong:

  import 'framework7-vue/dist/framework7-vue.min.css';

  correct:

  import 'framework7/framework7-bundle.min.css';

  Framework7's core CSS (including themes) is imported directly from the `framework7` package, not `framework7-vue`. Choose `framework7-bundle.min.css` for all styles, or specific themes like `framework7/framework7-ios.min.css`.

Quickstart

This quickstart demonstrates a basic Framework7 Vue application. It initializes Framework7, registers the Vue plugin, imports necessary CSS, and sets up a root `f7-app` component with a simple page, navbar, and a button that interacts with the Framework7 dialog API.

import { createApp } from 'vue';
import Framework7 from 'framework7/lite-bundle'; // Import Framework7 core JS
import Framework7Vue from 'framework7-vue'; // Import Framework7 Vue plugin
import 'framework7/framework7-bundle.min.css'; // Import Framework7 styles (includes all themes)

// Initialize Framework7 Vue plugin
Framework7.use(Framework7Vue);

const App = {
  template: `
    <f7-app :params="f7params">
      <f7-view main url="/"></f7-view>
    </f7-app>
  `,
  data() {
    return {
      f7params: {
        name: 'My F7 App',
        theme: 'auto', // Detect iOS or Material theme automatically
        routes: [
          {
            path: '/',
            component: {
              template: `
                <f7-page>
                  <f7-navbar title="Welcome" back-link="Back"></f7-navbar>
                  <f7-block strong>
                    <p>This is a simple Framework7 Vue application.</p>
                    <f7-button fill @click="openAlert">Show Alert</f7-button>
                  </f7-block>
                </f7-page>
              `,
              methods: {
                openAlert() {
                  this.$f7.dialog.alert('Hello from Framework7!');
                }
              }
            }
          }
        ]
      }
    };
  },
  mounted() {
    this.$f7ready((f7) => {
      console.log('Framework7 is ready!', f7);
      // You can now safely use f7 APIs here, e.g., f7.dialog.alert('App mounted!');
    });
  }
};

const app = createApp(App);
app.mount('#app');