Document Instaclick (#157)

* Document Instaclick * Copy edits * Document it's enabled by default and how to disable it programatically * InstaClick -> InstantClick
hotwired · Feb 7, 2024 · 704ca23 · 704ca23
1 parent 0b2c287
commit 704ca23
Show file tree

Hide file tree

Showing 2 changed files with 57 additions and 0 deletions.
diff --git a/_source/handbook/02_drive.md b/_source/handbook/02_drive.md
@@ -304,6 +304,61 @@ If the form submission is a GET request, you may render the directly rendered re
 
 Servers may also respond to form submissions with a [Turbo Streams](streams) message by sending the header `Content-Type: text/vnd.turbo-stream.html` followed by one or more `<turbo-stream>` elements in the response body. This lets you update multiple parts of the page without navigating.
 
+## InstantClick
+
+Turbo can also speed up perceived link navigation latency by automatically loading links on `mouseenter` or `touchstart` events, and before the user clicks the link. This usually leads to a speed bump of 500-800ms per click navigation.
+
+InstantClick is enabled by default since Turbo v8, but you can disable it by adding this meta tag to your page:
+
+```html
+<meta name="turbo-prefetch" content="false">
+```
+
+To avoid prefetching links that the user is briefly hovering, Turbo waits 100ms after the user hovers over the link before prefetching it. But you may want to disable the prefetching behavior on certain links leading to pages with expensive rendering.
+
+You can disable the behavior on a per-element basis by annotating the element or any of its ancestors with `data-turbo-prefetch="false"`.
+
+```html
+<html>
+  <head>
+    <meta name="turbo-prefetch" content="true">
+  </head>
+  <body>
+    <a href="/articles">Articles</a> <!-- This link is prefetched -->
+    <a href="/about" data-turbo-prefetch="false">About</a> <!-- Not prefetched -->
+    <div data-turbo-prefetch="false"`>
+      <!-- Links inside this div will not be prefetched -->
+    </div>
+  </body>
+</html>
+```
+
+You can also disable the behaviour programatically by intercepting the `turbo:before-prefetch` event and calling `event.preventDefault()`.
+
+```javascript
+document.addEventListener("turbo:before-prefetch", (event) => {
+  if (isUJS(event.target) || isSavingData() || hasSlowInternet()) {
+    event.preventDefault()
+  }
+})
+
+function isUJS(link) {
+  return link.hasAttribute("data-remote")   ||
+         link.hasAttribute("data-behavior") ||
+         link.hasAttribute("data-method")   ||
+         link.hasAttribute("data-confirm")
+}
+
+function isSavingData() {
+  return navigator.connection?.saveData
+}
+
+function hasSlowInternet() {
+  return navigator.connection?.effectiveType === "slow-2g" ||
+         navigator.connection?.effectiveType === "2g"
+}
+```
+
 ## Preload Links Into the Cache
 
 Preload links into Turbo Drive's cache using `<a href="/" data-turbo-preload>Home</a>`.

diff --git a/_source/reference/events.md b/_source/reference/events.md
@@ -26,6 +26,8 @@ Turbo emits events that allow you to track the navigation lifecycle and respond
 
 * `turbo:before-cache` fires before Turbo saves the current page to cache.
 
+* `turbo:before-prefetch` fires before Turbo prefetches a link. Cancel this event to prevent prefetching.
+
 * `turbo:before-render` fires before rendering the page. Access the new `<body>` element with `event.detail.newBody`. Rendering can be canceled and continued with `event.detail.resume` (see [Pausing Rendering](/handbook/drive#pausing-rendering)). Customize how Turbo Drive renders the response by overriding the `event.detail.render` function (see [Custom Rendering](/handbook/drive#custom-rendering)). The `event.detail.renderMethod` will equal either `"replace"` or `"morph"`.
 
 * `turbo:before-stream-render` fires before rendering a Turbo Stream page update. Access the new `<turbo-stream>` element with `event.detail.newStream`. Customize the element's behavior by overriding the `event.detail.render` function (see [Custom Actions](/handbook/streams#custom-actions)).