Building a Multi-Page UI

Previous Next

Almost no real app is a single screen. As soon as you need a home screen, a details screen, and a settings screen, you have to decide how your app moves between them. In a Cordova app there are two fundamentally different approaches to this, and picking the right one early saves a lot of restructuring later.

Two Approaches to Multi-Screen Navigation

Approach	How It Works
Single Page App (SPA) style	One `index.html` file. All "screens" are `<div>` blocks already present in the DOM (or injected dynamically). JavaScript shows and hides them to simulate navigation — there is no real page reload, ever.
Multi-Page style	Separate `.html` files (`index.html`, `details.html`, `settings.html`...). Navigating uses ordinary `<a href="details.html">` links, and the WebView performs a real full page load/reload each time, just like navigating a normal website.

Why SPA Style Is Generally Preferred for Hybrid Apps

Multi-page style is simpler to reason about at first — it's exactly how a normal multi-page website works — but it comes with real downsides inside a WebView shell pretending to be a native app:

Visible reload flash — each navigation is a real page load, so users briefly see a blank white screen or a flash of unstyled content between pages, which reads as janky rather than "app-like."
Lost JavaScript state — every full page load resets all your JavaScript variables, timers, and event listeners; anything you want to persist across screens has to be written to localStorage (see Local Storage & Persistence) and read back on the next page, which is extra plumbing for what should be simple in-memory state.
Slower transitions — parsing and rendering a fresh HTML document is measurably slower than toggling CSS on elements already in memory.

SPA style avoids all three: because there's no real navigation, there's no reload flash, JavaScript state naturally persists across "screens" (they're just divs in the same running page), and transitions can be instant, or animated smoothly with CSS. This is why virtually every serious Cordova app — and every major hybrid UI framework covered on the next page — is built SPA-style under the hood, even if it doesn't look like one from the outside.

Full Worked Example: Simple SPA-Style Navigation

Two "pages" living in the same index.html, toggled by adding/removing a .hidden class, driven by a tiny router function:

<div id="page-home" class="page">
    <h2>Home</h2>
    <p>Welcome! Tap a product to see its details.</p>
    <button onclick="showPage('page-details')">View Details</button>
</div>

<div id="page-details" class="page hidden">
    <h2>Product Details</h2>
    <p>Here's more information about the selected product.</p>
    <button onclick="showPage('page-home')">Back to Home</button>
</div>

/* Only one .page is visible at a time */
.hidden { display: none; }

function showPage(pageId) {
    // Hide every page, then reveal only the one we want
    var allPages = document.querySelectorAll('.page');
    for (var i = 0; i < allPages.length; i++) {
        allPages[i].classList.add('hidden');
    }
    document.getElementById(pageId).classList.remove('hidden');
}

Note: This is correct, plain HTML/CSS/JavaScript — it doesn't need Cordova at all to work, which is exactly the point: the "navigation" here is just DOM show/hide logic running inside the WebView, with no plugin involved. It's correct, real code, but this website's own project doesn't run a Cordova build, so paste it into your own project's files to try it live.

The Android Back Button Is a Real Consideration

Once your app has multiple "pages" (SPA-style or not), you must think about Android's hardware or gesture back button. By default, Cordova's WebView treats the back button as "leave the app" — if you don't handle it yourself, a user viewing your details screen who presses back will exit the entire app instead of returning to the home screen, which feels broken and is a very common bug in first Cordova apps. You handle this explicitly with the backbutton event:

document.addEventListener('deviceready', onDeviceReady, false);

function onDeviceReady() {
    document.addEventListener('backbutton', function(event) {
        var detailsPage = document.getElementById('page-details');

        if (!detailsPage.classList.contains('hidden')) {
            // We're on the details "page" -- go back to home instead of exiting
            event.preventDefault();
            showPage('page-home');
        }
        // Otherwise (already on home), let the default behavior exit the app
    }, false);
}

Note: This is correct, real Cordova JavaScript for the backbutton event — but this website's own project doesn't run a Cordova build, so you won't see it actually execute on this page. Copy it into your own project to try it on a real Android device or emulator.

What Comes Next

Handling every screen transition, back-button case, and animation by hand works fine for a small app with two or three screens, but it gets tedious fast as an app grows. This is exactly the problem dedicated hybrid UI frameworks solve — they provide a ready-made SPA-style navigation system (with history stacks, transition animations, and back-button handling built in) on top of native-looking components. The next page introduces the most common ones.

Next steps: Head to Using a UI Framework to see how frameworks like Framework7 and Onsen UI handle this navigation complexity for you.

Previous Next