Skip to content

Home

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

Flux gives server-rendered applications a fluid user experience without asking us to abandon plain HTML forms, links, and full-page responses.

Flux respects Hypermedia - if your page is HTML, you should always serve HTML pages to the browser, without the need for computer languages like JSON to update the page state.

Important

Flux is built as a standalone library, but the main intention is to be used with PHP.GT/WebEngine - Flux is shipped by default in WebEngine applications. All examples and server-side code use plain PHP, but any language or framework could be used. For more information about how WebEngine takes full advantage of Flux, see https://www.php.gt/docs/webengine/flux/

In this guide, we will start with a simple form, then steadily add more of Flux's behaviour until we have covered the whole library. The examples in this repository all follow the same idea: we keep rendering complete HTML on the server, and Flux automatically swaps the right part of the page in the browser.

What we'll build up to

  • Background form submissions using ordinary <form> elements.
  • Scoped page updates using data-flux directives.
  • Link navigation without a full-page refresh.
  • Live polling regions that keep themselves up to date.
  • Autosave, attribute refreshes, and request rate limiting.
  • Reattaching our own JavaScript event handlers after Flux swaps DOM elements.

Note

Flux expects the server response to be a full HTML document. We do not need to build bespoke JSON APIs or partial templates just to use it.

The guiding idea

Flux is a progressive enhancement library - it enhances normal client/server browser usage rather than replacing it.

  • A Flux form is still a real form, that still makes the same POST request to your server-side code.
  • A Flux link is still a real link, that still makes the same GET request.
  • A live region is still rendered by the server, without having to change any server-side code.

That means our application should be written to work without JavaScript first, and then Flux will automatically enhance the user experience to make it more fluid.

Where to go next

Quick preview

<form method="post" data-flux="update-inner">
	<output>0</output>
	<button name="do" value="increment" data-flux="submit">Increment</button>
</form>

<textarea>Type something into this textarea - the state will be persisted after clicking the increment button above.</textarea>

Here we let the button submit in the background, then tell Flux to replace only the form's inner HTML with the matching form from the returned document. The textarea on the page is just for show - without Flux, clicking the button would cause a full-page refresh, losing any state within the textarea.

Scale this up to a full fledged web application, and you can imagine many forms with multiple live-updating elements, all working with the richness of a Single Page Application.

Start by Installing, so the library is loaded correctly before we add any directives.

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

Clone this wiki locally