PHP.GT

Link navigation

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 after link navigation and pushes a history state for the fetched URL. If the browser popstate event fires, Flux reloads the document so the back and forward buttons do not leave us with stale partial state.

Flux also stores the scroll position for each Flux link entry:

  • when we follow a Flux link, the new page is stored at the top
  • when we press Back, Flux restores the previous page’s scroll position
  • when we press Forward again, Flux restores the link destination to the top

This keeps Flux link navigation close to the behaviour we expect from ordinary browser navigation, while still allowing part of the page to stay outside the update target.

By default, Flux restores scroll positions immediately. To make link scrolling and history restoration smooth, add data-flux-scroll="smooth" to the element whose scroll position should be managed:

<main data-flux="update-link" data-flux-scroll="smooth">
	<nav>
		<a href="/reports" data-flux>Reports</a>
	</nav>
</main>

Flux uses the nearest data-flux-scroll ancestor of the clicked link. If that element is a normal page wrapper, Flux scrolls that element. If the attribute is on <body> or <html>, Flux scrolls the window instead, which is useful for page-wide behaviour.

data-flux-scroll="auto" keeps the immediate behaviour. This means we can make one scrolling panel smooth without changing the rest of the page.

[!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.