htmx/preload.md at 8a4c2ba1735859e9e287600ed8ffdbd77b4582ea

mirror of https://github.com/bigskysoftware/htmx.git synced 2025-09-28 21:41:40 +00:00

Ben Pate 8a4c2ba173 Add documentation

This should document everything in the extension.  Please let me know if there are any typos or mistakes.

2021-01-01 22:08:20 -07:00

5.9 KiB

Raw Blame History

layout	title
layout.njk	</> htmx - high power tools for html

The `preload` Extension

The preload extension allows you to load HTML fragments into your browser's cache before they are requested by the user, so that additional pages appear to users to load nearly instantaneously. Its behavior can be customize to fit your applications needs and use cases. IMPORTANT: Preloading content judiciously can improve your web application's perceived performance, but preloading too many resources can negatively impact your visitors' bandwidth and your server performance by initiating too many unused requests. Use this extension carefully

Usage

Load the the preload.js script into your website's Javascript, and register the extension with htmx. To prevent you from accidentally preloading every link on your webpage, you must explicityly add a "preload" attribute to each resource you want to preload. In addition, only GET transactions are preloaded, not POST, PUT, or DELETE. If you use this extension and do not see resources being preloaded correctly, check these two things first.

<body hx-ext="preload">
    <h1>What Works</h2>
    <a href="/server" preload>Requested using a standard XMLHttpRequest() and default options (below)</a>
    <button hx-get="/server" preload>Request includes standard htmx headers.</button>

    <h1>What WILL NOT WORK</h1>
    <a href="/server">This link WILL NOT be preloaded because it does not have an explicit "preload" attribute</a>
    <a hx-post="/server" preload>This resource WILL NOT be preloaded because it is an HX-POST transaction.</a>
</body>

Configuration Options

Defaults for this extension are chosen to balance users' perceived performance with potential load on your servers from unused requests. As a developer, you can modify two settings to customize this behavior to your specific use cases. Both options are inherited by child nodes, so (for example) you can modify them once on your body tag, and your settings will be used throughout your web page.

preload-on

This determines the event that triggers the HTML resource to be preloaded. Common options are:

mouseover [DEFAULT] When the user's mouse moves over this resource, it triggers the resource to be preloaded. NOTE, to ensure that you do not preload resources when a mouse moves over an element quickly (for instance, while scrolling down the page) a default 100ms timeout is set on this event. If the mouse leaves the element before this timeout expires, then the resource is not preloaded.
mousedown Triggers when the user presses the mouse down, but before they release the button (mouseup). This gives your server a (roughtly) 100ms head start on completing the request compared to a reguar click.
load Triggers the preload as soon as the page (or fragment) is processed by htmx. Does not wait for a user-generated event. Use this option sparingly.
custom event names You can also trigger preloads on any other custom events on the webpage, includeing htmx: events generated by htmx itself.

<body hx-ext="preload" preload-on="mousedown">
    <a href="/server" preload>Preloaded when the user presses the mouse down</a>
    <div hx-get="/server" preload preload-on="load">Preloaded 100ms after the page/fragment is processed by htmx</div>
</body>

preload-wait

This option sets a waiting period after the triggering event fires. You can enter any timespan recognized by htmx: either in seconds (s) or milliseconds (ms), though in most cases the extension will "do the right thing" and you should not need to tune this value. Default values for this depend on the event that triggers the extension.

For mouseover events, the default for this option is 100ms. If the user's mouse leaves the element within this time period, then the preload is canceled. This prevents resources from being preloaded when the user scrolls or moves their mouse over a large area of the page. If the user's mouse has not left the element after this time period, then the resource is preloaded. Typical users hover over links for several hundred milliseconds before they click, which leaves plenty of time for your server to generate the resource before the click event begins. Test your own hover timing here.

For all other events (including mousedown, load, and other custom events) this defaults to 0ms, which begins the preload without further delay.

<body hx-ext="preload" preload-on="mouseover">
    <a href="/server" preload>Preloaded 100ms after the user hovers (if they don't leave beforehand)</a>
    <div hx-get="/server" preload preload-wait="0ms">Preloaded immediately after hover (though generally a bad idea)</div>
</body>

About Touch Events

To accomodate touchscreen devices, an additional ontouchstart event handler is added whenever you specify a mouseover or mousedown trigger. This extra trigger fires immediately (no waiting period) whenever the user touches the screen, saving you 300ms of waiting time on Android, and 450ms on iOS.

Limitations

Links must be marked explicitly with a preload attribute.
Only resources from the same server can be preloaded. Resources from third-party websites (including CDNs) will not be preloaded.
Only GET transactions (including <a href=""> and hx-get="") can be preloaded. Following REST principles, GET transactions are assumed to not make any significant changes to a resource. Transactions that can potentially make a change (such as POST, PUT, and DELETE) will not be preloaded under any circumstances.

Credits

The behavior for this plugin was inspired by the work done by Alexandre Dieulot on InstantClick, which is released under the MIT license.

Source

https://unpkg.com/htmx.org/dist/ext/preload.js

5.9 KiB Raw Blame History

The preload Extension