PHP.GT

List of flux attributes

This page is the reference sheet for every public Flux directive and attribute. The rest of the guide introduces them gradually, but it’s useful to have them listed here in one place.

data-flux

data-flux on a <form>

Shorthand for an automatic Flux container. Flux listens for the form’s submit event and submits it in the background.

<form method="post" data-flux>
	<button name="do" value="save">Save</button>
</form>

data-flux on an <a>

Shorthand for data-flux="link".

<a href="/next-page" data-flux>Next page</a>

data-flux on a <button>

Shorthand for data-flux="submit".

<button name="do" value="save" data-flux>Save</button>

data-flux="update" and data-flux="update-outer"

Replace the whole element with the matching element from the returned HTML document.

data-flux="update-inner"

Keep the element itself, but replace its contents with the matching element’s contents from the returned document.

data-flux="update-link"

Apply an outer replacement only for Flux link navigation.

data-flux="update-link-inner"

Apply an inner replacement only for Flux link navigation.

data-flux="live" and data-flux="live-outer"

Poll the current page URL and replace the whole element on each refresh.

data-flux="live-inner"

Poll the current page URL and replace only the contents of the element.

data-flux="update-attributes"

Refresh just the element attributes from the matching element in the returned document.

data-flux="submit"

Attach background submission to the containing <button>’s form.

data-flux="link"

Attach background navigation to an anchor element.

data-flux="autosave"

Attach change-driven background submission to the containing form. This directive must be placed on a <button>, and Flux hides that button automatically.

<form method="post">
	<input name="title" />
	<button name="do" value="save" data-flux="autosave">Save</button>
</form>

data-flux="drag-order"

Enhance a server-rendered ordering form into a drag-and-drop control. This directive can be placed either on the sortable item or on the <form> inside it.

Flux expects the sortable host to contain a form with:

  • an input named order
  • a button named do
<ul data-flux="update">
	<li data-id="1" data-flux="drag-order">
		<form method="post">
			<input type="hidden" name="id" value="1" />
			<label>
				<span>Move to order</span>
				<input type="number" name="order" />
				<button name="do" value="move">Move</button>
			</label>
		</form>
		<span>one</span>
	</li>
</ul>

Flux hides the order input, the do button, and any containing labels, then adds a .drag-handle element. When the item is dropped, Flux writes the zero-based position into order and submits the form in the background.

Rate and timing attributes

data-flux-scroll

Control how Flux restores scroll positions during link navigation and browser history navigation.

This attribute can be placed on the scrolling element that contains a Flux link:

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

Supported values are:

  • auto - restore scroll positions immediately
  • smooth - restore scroll positions with smooth browser scrolling

Flux uses the nearest data-flux-scroll ancestor of the clicked link. On ordinary elements, Flux stores and restores that element’s own scrollTop and scrollLeft. On <body> or <html>, Flux stores and restores the window scroll position, which gives page-wide behaviour.

data-flux-rate

Control how often a Flux interaction can happen. On buttons and links it throttles requests, and on live elements it sets the polling interval.

<button data-flux="submit" data-flux-rate="1">Save</button>
<a href="/news" data-flux="link" data-flux-rate="2">Refresh</a>
<time data-flux="live" data-flux-rate="5">12:00:00</time>

The values are in seconds.

On live elements, omitting data-flux-rate leaves Flux using a one-second interval.

Matching rule

If a Flux element has an id attribute, the matching id of subsequent responses will be used when replacing. However, flux does not require you to add an id to elements that need replacing. Instead, it records the current element’s path through the DOM and looks up the element at that same path in the new document.

[!IMPORTANT] When we return a fresh HTML document from the server, the structure around Flux targets should stay consistent enough for Flux to find the matching element in the same place.

If you want the walkthrough version of the docs rather than the reference sheet, go back to your first Flux form or continue on to examples.