Getting Started / Overview

Docs Getting Started

Overview

It's highly recommended that you read the Turbo Handbook before continuing. However, we'll provide a quick intro here and link to the Turbo documentation when relevant.

Turbo is the heart of Hotwire. In essence, it's a JavaScript library that turns regular web applications (aka. multi-page web applications) into something that feels like a single-page application (SPA).

It provides a set of components that allow us to build modern web applications with minimal JavaScript. It relies on sending HTML Over The Wire (hence the name) instead of JSON, which is how JavaScript-heavy web applications are typically built, consuming some sort of JSON API.

When Turbo.js is started in the browser, it intercepts link clicks and form submissions and converts them into fetch requests (aka. AJAX) instead of letting the browser do a full page refresh. The component in Turbo that handles this behavior is called Turbo Drive.

Turbo Drive does the heavy lifting of the SPA feel in our application. Just by turning it on, the improvement in perceived performance should be noticeable. By default, Turbo replaces the contents of the page's <body> tag with the one from the response to the link click or form submission.

Additionally, since Turbo 8, we can also instruct Turbo to morph the page instead of just replacing its contents, by adding meta tags to the pages where we want it enabled:

html
<meta name="turbo-refresh-method" content="morph">
<meta name="turbo-refresh-scroll" content="preserve">

Alternatively, Turbo Laravel provides some Blade components to make it easier (and autocomplete friendlier) to interact with these Turbo page configurations:

blade
<x-turbo::refreshes-with method="morph" scroll="preserve" />

Turbo Drive does a lot for us, and with morphing it gets even more powerful, but sometimes you may want to decompose a page into independent sections (for different reasons, such as having more control over HTTP caching for these sections). For these use cases, Turbo offers Turbo Frames.

Turbo Frames are custom HTML tags that Turbo provides. You can think of them as "modern iframes", if you will. When link clicks or form submissions happen inside a Turbo Frame, instead of replacing or morphing the entire page, Turbo only updates that specific Turbo Frame's content. It does so by extracting the matching Turbo Frame (one with the same DOM ID) from the response.

Here's how you can use Turbo Frames:

html
<turbo-frame id="my_frame">
    <h1>Hello, World!</h1>

    <a href="/somewhere">Click me</a>
</turbo-frame>

Alternatively, you may want a Turbo Frame to fetch its contents immediately instead of waiting for a user interaction. For that, you may add a [src] attribute to the Turbo Frame tag with the URL Turbo should fetch the content from. This technique is called Lazy-loading Turbo Frames:

blade
<turbo-frame id="my_frame" src="{{ route('my.page') }}">
    <p>Loading...</p>
</turbo-frame>

A lazy-loaded Turbo Frame will dispatch a fetch request (aka. AJAX) as soon as it enters the DOM, replacing its contents with the contents of a matching Turbo Frame in the response HTML. Optionally, you may add a [loading=lazy] attribute to the lazy-loaded Turbo Frame so Turbo only fetches its content when the Turbo Frame becomes visible (within the viewport):

blade
<turbo-frame id="my_frame" src="{{ route('my.page') }}" loading="lazy">
    <p>Loading...</p>
</turbo-frame>

You may also trigger a Turbo Frame with forms and links that are outside of the frame tag by adding a [data-turbo-frame] attribute to the link, form, or submit button, passing the ID of the Turbo Frame:

blade
<div>
    <a href="/somewhere" data-turbo-frame="my_frame">I'm a link</a>

    <turbo-frame id="my_frame">
        ...
    </turbo-frame>
</div>

Turbo Drive and Turbo Frames allow us to build A LOT of different kinds of interactions. However, sometimes you may want to update multiple sections of a page after a form submission, for instance. For those use cases, Turbo provides another custom HTML tag called Turbo Streams.

Turbo annotates the form submissions it intercepts, which tells our back-end application that Turbo is on, so we can return a special type of response that only contains Turbo Streams. Turbo.js does so by adding a custom MIME type of text/vnd.turbo-stream.html to the Accept HTTP Header.

Turbo Streams allow for more fine-grained control over page updates. For instance, here's an example of a Turbo Stream that appends a new comment to a comments section:

html
<turbo-stream action="append" target="comments">
    <template>
        ...
    </template>
</turbo-stream>

The [action=append] will add the contents of the <template></template> tag to the element whose DOM ID matches the [target=comments] attribute, so #comments in this case.

There are 8 default Turbo Stream actions in Turbo:

Action Description
append Appends the contents of the <template> tag into the target or targets
prepend Prepends the contents of the <template> tag to the target or targets
update Updates the target or targets with the contents of the <template> tag (keeps the targeted elements around)
replace Replaces the target or targets with the contents of the <template> tag (actually removes the targets)
before Inserts the contents of the <template> tag before the targeted elements
after Inserts the contents of the <template> tag after the targeted elements
remove Removes the targeted elements (doesn't require a <template> tag)
refresh Signals Turbo Drive to do a page refresh (requires neither a <template> tag nor a target)

All the default Turbo Stream actions, except the refresh one, require a target or a targets attribute. The target attribute expects the DOM ID of the target element, while the targets attribute expects a CSS selector matching the target element(s).

All of the default actions require the contents of the new or updated element to be wrapped inside a <template> tag, except for the remove and refresh actions. That's because Turbo Stream tags are activated simply by adding them to the document. They perform their action and are then removed from the DOM. Wrapping the content in a <template> ensures it isn't visible in the browser while the stream is being activated.

I keep saying "default actions" because Turbo also allows us to create our own custom actions:

js
import { StreamActions } from "@hotwired/turbo"

StreamActions.log = function () {
  console.log(this.getAttribute("message"))
}

In this case, we can use this action like so:

html
<turbo-stream action="log" message="Hello World"></turbo-stream>

This will print "Hello World" to the DevTools Console. With custom actions, you can do pretty much anything on the document.

So far, this has all been vanilla Hotwire and Turbo.