Framework7 React Integration

Common errors

• TypeError: Cannot read properties of undefined (reading 'dialog')

  cause Attempting to access `Framework7.instance` or its methods (e.g., `Framework7.instance.dialog`) before the Framework7 app is fully initialized.
  fix Ensure all calls to `Framework7.instance` or its APIs are placed within the `f7ready()` callback, or inside a `useEffect` hook that depends on `f7ready` having completed, guaranteeing the instance is available.

• Module not found: Can't resolve 'framework7-react' in '...' or 'Module not found: Can't resolve 'framework7/css/bundle''

  cause The `framework7-react` package, its core `framework7` dependency, or the required CSS bundle is not installed or incorrectly referenced.
  fix Run `npm install framework7-react framework7 react react-dom` (or `yarn add`). Also, ensure you have `import 'framework7/css/bundle';` (or specific theme CSS) in your root React component or main entry file.

• Framework7 components must be used inside Framework7 App component.

  cause A component provided by `framework7-react` (e.g., `f7Page`, `f7Navbar`) is being rendered outside of the main `<App>` component wrapper.
  fix Ensure that all Framework7 React components are direct or indirect children of the `<App>` component provided by `framework7-react` to ensure they have access to the Framework7 context.

Warnings

• breaking The `dynamicNavbar` functionality has been completely removed in v9.0.0. Components relying on this feature will break.
  Fix: Refactor layouts to use static Navbars or implement custom solutions for dynamic header behavior. Review your app's navigation structure for compatibility.
• breaking In v9.0.0, the default text for Navbar back links is now empty, favoring an icon-only approach.
  Fix: If text is required for back links, explicitly set the `backLinkText` prop on `f7Navbar` or `f7Page` components.
• gotcha Version 9.0.0 introduces significant UI/UX changes for both iOS (new iOS 26 styles) and Material Design (updated Material You specs, new color schemes). Existing custom styles or themes might require adjustments.
  Fix: Thoroughly review your application's UI after upgrading. Test components across both iOS and Material Design themes to identify and resolve visual regressions or inconsistencies.

Install

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

Imports

• App
  wrong:

  const App = require('framework7-react').App;

  correct:

  import { App } from 'framework7-react';

  The primary component to initialize Framework7. Use named import. CommonJS `require` is generally not recommended for modern React/F7 applications.
• Framework7
  wrong:

  import Framework7 from 'framework7';

  correct:

  import { Framework7 } from 'framework7-react';

  This import from 'framework7-react' provides the TypeScript type and a reference to the global Framework7 instance after initialization. The actual instance becomes accessible via `Framework7.instance` once the `<App>` component mounts and initializes.
• f7ready
  wrong:

  Framework7.instance.ready(() => {});

  correct:

  import { f7ready } from 'framework7-react';

  A utility function specific to `framework7-react` to execute code when the Framework7 instance is fully initialized and ready, ensuring `Framework7.instance` is available. Prefer this over direct Framework7 core methods in a React context.
• f7Page, f7Navbar
  wrong:

  import { Page, Navbar } from 'framework7-react';

  correct:

  import { f7Page, f7Navbar } from 'framework7-react';

  Most Framework7 React components are prefixed with `f7` to avoid naming conflicts and clearly denote their origin. Always use the `f7` prefixed versions when importing components.

Quickstart

Initializes a basic Framework7 React application with a single view and page, demonstrating app setup and component usage, including accessing the Framework7 API.

import React, { useEffect } from 'react';
import { 
  App, 
  View, 
  Page, 
  Navbar, 
  Block, 
  Button, 
  f7ready, 
  Framework7 
} from 'framework7-react';

// Framework7 parameters
const f7params = {
  name: 'My F7 React App',
  theme: 'auto', // Detect iOS or MD theme automatically
  routes: [
    {
      path: '/',
      component: () => (
        <Page>
          <Navbar title="Hello F7 React" />
          <Block strong>
            <p>Welcome to a basic Framework7 React application!</p>
            <p>This demonstrates a simple page with a functional button.</p>
            <Button fill onClick={() => Framework7.instance?.dialog.alert('Button clicked!')}>
              Click Me
            </Button>
          </Block>
        </Page>
      ),
    },
  ],
};

const MyApp: React.FC = () => {
  useEffect(() => {
    f7ready(() => {
      console.log('Framework7 instance is ready and accessible via Framework7.instance');
      // Example: Framework7.instance.router.navigate('/some-other-page');
    });
  }, []);

  return (
    <App {...f7params}>
      {/* Main View for the app */}
      <View main url="/" />
    </App>
  );
};

export default MyApp;

// To render, typically in index.tsx:
// import React from 'react';
// import { createRoot } from 'react-dom/client';
// import MyApp from './MyApp';
// import 'framework7/css/bundle'; // Crucial: Import Framework7 styles
//
// const rootElement = document.getElementById('root');
// if (rootElement) {
//   createRoot(rootElement).render(<MyApp />);
// }