Skip to content

Link navigation

Jump to bottom
Greg Bowler edited this page Apr 10, 2026 · 4 revisions

Flux can intercept ordinary links and fetch the destination document in the background. This keeps navigation fluid while we still serve complete HTML pages from the server.

example/04-links.php, example/04a-page1.php, and example/04b-page2.php form a small three-page walkthrough of this behaviour.

Turn an anchor into a Flux link

We can either write data-flux="link" explicitly or use shorthand data-flux on the <a> element:

<a href="/reports" data-flux>Reports</a>

When the link is clicked, Flux:

  1. prevents the browser's default navigation
  2. fetches the linked document in the background
  3. pushes a history state with the new URL
  4. applies any link-capable update targets

Link-only update targets

When a link is clicked, the expected behaviour of the browser is distinctively different from when a form submits: a link should replace the content of the page, not just small components of the page.

We can mark which element contains the page content with data-flux="update-link". This element will be updated only when a link is clicked.

<main data-flux="update-link">
	<nav>
		<a href="./04-links.php" data-flux>Landing page</a>
		<a href="./04a-page1.php" data-flux>Page 1</a>
		<a href="./04b-page2.php" data-flux>Page 2</a>
	</nav>
</main>

That means the <main> element refreshes for Flux links, but not for ordinary Flux form submissions inside the page.

There's also data-flux="update-link-inner" if we want to keep the outer element and replace only its contents.

Mixing link navigation with forms

The link example deliberately mixes both behaviours on the same page:

  • the page shell uses update-link
  • the small cards use update-inner
  • the scratchpad <textarea> sits outside both targets

This lets us preserve some state across navigation while still allowing local in-page updates.

Scrolling and browser history

Flux scrolls to the top during link navigation and pushes a history state for the fetched URL. If the browser popstate event fires, Flux reloads the document so the back button does not leave us with stale partial state.

[!INFO] Forms whose <form> element has an action attribute are also treated as navigation-style responses, so they use the link document handler and update history as well.

[!INFO] While a Flux link request is in flight, Flux adds the class flux-link-waiting to both the clicked link and the page <body>. We can style global navigation loading states, or just the active link, with that class in CSS.

With links working, we can learn about live updates that keep elements constantly up to date.

PHP.GT/Flux is a separately maintained component of PHP.GT/WebEngine.

Clone this wiki locally