Turbo

Turbo is a library designed to reduce the amount of custom JavaScript required in web applications by sending HTML over the wire. It provides four primary mechanisms for enhancing web and mobile experiences:

• Turbo Drive: Accelerates navigation by intercepting link clicks and form submissions to replace full page reloads with AJAX requests, updating the browser history without a complete refresh.
• Turbo Frames: Allows you to decompose a page into independent, scoped contexts. Navigation within a frame is restricted to that frame, and frames can be lazily loaded.
• Turbo Streams: Delivers targeted page changes (via WebSocket or in response to form submissions) using HTML and a set of CRUD-like actions.
• Turbo Native: Enables web applications to power native iOS and Android apps, providing seamless transitions between web content and native UI components.

The library automatically attaches itself to the global window.Turbo object. This object includes all core Turbo functionality, Turbo Elements, and StreamActions. This is useful for accessing Turbo from inline scripts or other libraries that do not use ES modules.

// If Turbo.start() has been called, you can access it anywhere:
console.log(window.Turbo);
// Includes core methods, elements, and StreamActions

Turbo provides three primary custom elements for managing scoped navigation and real-time updates via WebSockets or Server-Sent Events:

1. <turbo-frame>: Used to isolate parts of a page. Navigations within a frame are scoped to that frame, updating only its content.
2. <turbo-stream>: Used to receive and apply incremental updates to the DOM (e.g., appending or replacing elements).
3. <turbo-stream-source>: Used to establish a connection to a stream source (like a WebSocket or SSE endpoint) to receive <turbo-stream> updates.

<!-- Example of the elements defined by Turbo -->
<turbo-frame id="message_1">
  <!-- Content that can be updated independently -->
</turbo-frame>

<turbo-stream-source url="/cable" connected_callback="onConnected"></turbo-stream-source>

To enable Turbo in your application, you must call Turbo.start(). This initializes the library, sets up polyfills, and attaches Turbo to the global window.Turbo object. Once started, Turbo will intercept link clicks and form submissions to perform fast, AJAX-driven page transitions.

import * as Turbo from "@hotwired/turbo";

Turbo.start();

The @hotwired/turbo package automatically defines the following custom elements if they are not already registered in the customElements registry:

• turbo-frame (via FrameElement)
• turbo-stream (via StreamElement)
• turbo-stream-source (via StreamSourceElement)

<turbo-frame> is a custom element that contains a fragment of HTML which is updated based on navigation within it (e.g., via links or form submissions). When a link or form inside a <turbo-frame> is triggered, Turbo intercepts the request and updates only the content within that specific frame instead of performing a full page reload.

Basic Usage

<turbo-frame id="messages">
  <a href="/messages/expanded">
    Show all expanded messages in this frame.
  </a>

  <form action="/messages">
    Show response from this form within this frame.
  </form>
</turbo-frame>

Turbo allows you to intercept form submissions to show a confirmation dialog. By default, it looks for a data-turbo-confirm attribute on the submitter (e.g., a button) or the form itself.

You can customize this behavior by providing a custom function in the Turbo configuration via config.forms.confirm. This function should accept the confirmation message, the form element, and the submitter, and return a Promise that resolves to a boolean.

If no custom function is provided, Turbo defaults to using the native browser confirm() method.

// Example of overriding the confirmation logic
// Note: This assumes access to the Turbo config object
config.forms.confirm = async (message, form, submitter) => {
  // Use a custom UI modal instead of browser confirm()
  return await myCustomModal.show(message);
};

While some top-level setter functions exist, they are deprecated. You should use the config object for configuration.

Deprecated Setters (Use config instead):

• setProgressBarDelay(delay) $\rightarrow$ config.drive.progressBarDelay = delay
• setConfirmMethod(confirmMethod) $\rightarrow$ config.forms.confirm = confirmMethod
• setFormMode(mode) $\rightarrow$ config.forms.mode = mode

import { config } from "@hotwired/turbo"

config.drive.progressBarDelay = 300
config.forms.confirm = (message) => window.confirm(message)
config.forms.mode = "ajax"