Diagnosing Blank Pages and Missing Transitions in Framework7 Router Navigation

Recognizable Condition

When navigating to a new view using Framework7's router with pushState enabled, the screen stays blank, the URL in the address bar does not change, and no page transition animation occurs. The browser console may show no errors, making the failure silent.

Cause and Diagnostic Table

Ordered Checks

1. Validate route definitions. Open the file where routes are declared (commonly routes.js or inside app.js). Ensure each route object has a path that matches the navigation URL pattern. For dynamic segments, use the correct syntax: /user/:userId/.
2. Confirm component registration. For each route, the component (or componentUrl) must point to a valid module. If using ES modules, the import must be present and the component exported. Example:

   // routes.js
   import UserProfile from './pages/user-profile.js';
   export default [
     { path: '/user/:userId/', component: UserProfile },
     // ...
   ];

3. Inspect page template content. The component's template (or render function) must contain at least one visible DOM element. An empty template (e.g., <template></template>) will produce a blank page even if the route matches.
4. Verify router initialization parameters. In the Framework7 app constructor, ensure pushState: true is set. Also check that view components have pushState enabled if overridden per view.

   const app = new Framework7({
     // ...
     pushState: true,
     pushStateRoot: undefined, // or your subdirectory path
     // ...
   });

5. Check for CSS conflicts. Use DevTools Elements panel to inspect the incoming page element (.page). Look for transform, opacity, visibility, or z-index rules that could hide it. Common culprits are global resets or third-party UI libraries applying transform: translateZ(0) on .view.
6. Review console and network for module errors. Open DevTools Console and Network tabs. Filter for JS errors or failed requests (404) on component files. A missing .js or .css file will prevent the page from rendering.

Fixes Tied to Findings

Route Path Mismatch

Adjust the path in the route definition to match the navigation URL. If the URL contains optional parameters or complex patterns, use a regex path: path: /^\/user\/(?\d+)\/?$/. After editing, reload the app and navigate again.

Missing Component Import

Add the import statement for the page component and include it in the routes array. Ensure the component file exports a valid Framework7 component (a plain object with a template or render function).

Empty Page Template

Add placeholder content to the component's template. Even a single <div>Loading...</div> will make the page visible and allow the router to attach transition classes.

PushState Disabled

Set pushState: true in the Framework7 app parameters. If the app runs in a subdirectory, also set pushStateRoot: '/my-app/' to match the base path. This change requires a full page reload to take effect.

CSS Transform Hiding Page

Remove or override the conflicting CSS rule. For example, if a global stylesheet sets .view { transform: translate3d(0,0,0); }, either delete it or add a more specific rule: .view { transform: none; }. Verify that the incoming page receives the .page-next and .page-current classes during transition.

Escalation Criteria

Escalate to a senior frontend engineer if:

• The blank page persists after completing all six checks above.
• Multiple unrelated routes exhibit the same blank-page behavior, suggesting a global router or Framework7 initialization issue.
• Framework7 router event hooks (routeChangeStart, routeChangeEnd) do not fire at all when navigation is triggered.

Verification After Fix

1. Reload the application in the browser.
2. Navigate to the previously failing route via a link or programmatic router.navigate('/user/123/').
3. Confirm that the page content appears, the URL updates in the address bar, and a transition animation runs.
4. Open DevTools Console and verify no errors related to module loading or route resolution appear.
5. Optionally, add temporary logging to router events to trace navigation:

   app.on('routeChangeStart', (route) => console.log('Start:', route.url));
   app.on('routeChangeEnd', (route) => console.log('End:', route.url));

Limitations

This guide covers the most common causes of blank pages and missing transitions in Framework7 v7/v8 with pushState routing. It does not address issues arising from custom router plugins, server-side rendering setups, or Cordova/Capacitor specific navigation quirks. If your project uses a non-standard build pipeline (e.g., Vite with non-standard aliasing), additional module resolution checks may be required.