data-turbo-* attributes are sometimes used to declare non-default behavior.
The turbo library has three main concepts it calls Drive, Frames and Streams.
Turbo Drive is nearly invisible. A developer doesn't directly interact with it in most cases. Adding the Turbo library on any HTML page automatically translates all
<a> (link) and
import * as Turbo from "@hotwired/turbo";
<!-- from a CDN --> <script type="module" defer> import Turbo from 'https://cdn.skypack.dev/@hotwired/turbo'; </script>
Turbo Frames (and Streams) is the exciting part of the Turbo library. So much behavior can be added to an app with Frames - still just by writing HTML! I believe there is too much to cover in this Hotwire overview, the next part in this series will be dedicated to Frames. Here is a quick preview of what Turbo Frames can do.
In an alternate reality I run a small coffee stand for people willing to wait for slow, manual coffee brewing methods. I offer pour-over, French press, and Aeropress coffees. The HTML for the self-serve brew method selection looks like this (simplified):
<h1>How shall I brew your ☕️</h1> <turbo-frame id="coffee_selection"> <div> <h3>Pour-over</h3> <p>... describes pour-over ...</p> <a href="choose_pour_over.html"> Pour my coffee </a> </div> <div> <h3>French press</h3> <p>... describes french press ...</p> <a href="choose_french_press.html"> (French) Press my coffee </a> </div> <div> <h3>Aeropress</h3> <p>... describes aeropress ...</p> <a href="choose_aeropress.html"> (Aero)Press my coffee </a> </div> </turbo-frame>
Wrapping the selection components in a
<turbo-frame> causes links inside the tag to only effect the context of that frame. Clicking links or submitting forms will not update the entire page, instead they expect HTML from the response to contain directions on how to update the frame. When the response has a matching
turbo-frame ID, the contents in the frame are replaced with the contents from the respective tag in the response.
<!-- choose_pour_over.html --> <turbo-frame id="coffee_selection"> <div> <h3>Pour-over</h3> <p>Great choice!</p> <p>Wait time 5 minutes</p> </div> </turbo-frame
<turbo-frame> tag did all the work. Clicking the "Pour my Coffee" link causes the contents of the file
choose_pour_over.html to be fetched and Turbo replaces the frame.
Turbo Streams adds HTML tags that can give more granular page update directions. The
<turbo-stream> tag supports HTML attributes that give instructions to replace certain parts of a page or to append or prepend HTML from inside the tag. It's a super powerful part of the Turbo library and deserves its own coverage. I plan on including a Turbo Stream article later in this series to demonstrate the huge potential of communicating front-end update instructions using plain HTML.
A similar replacement like the example above would be more explicit with Turbo Stream markup.
<turbo-stream action="replace" target="coffee_selection"> <template> <div> <h3>Pour-over</h3> <p>Great choice!</p> <p>Wait time 5 minutes</p> </div> </template> </turbo-stream>