Skip to content

Frames

Basic frame

Confines all navigation within the frame by expecting any followed link or form submission to return a response including a matching frame tag:

<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>

Eager-loaded frame

Works like the basic frame, but the content is loaded from a remote src first.

<turbo-frame id="messages" src="/messages">
Content will be replaced when /messages has been loaded.
</turbo-frame>

Lazy-loaded frame

Like an eager-loaded frame, but the content is not loaded from src until the frame is visible.

<turbo-frame id="messages" src="/messages" loading="lazy">
Content will be replaced when the frame becomes visible and /messages has been loaded.
</turbo-frame>

Frame targeting the whole page by default

<turbo-frame id="messages" target="_top">
<a href="/messages/1">
Following link will replace the whole page, not this frame.
</a>

<a href="/messages/1" data-turbo-frame="_self">
Following link will replace just this frame.
</a>

<form action="/messages">
Submitting form will replace the whole page, not this frame.
</form>
</turbo-frame>

Frame with overwritten navigation targets

<turbo-frame id="messages">
<a href="/messages/1">
Following link will replace this frame.
</a>

<a href="/messages/1" data-turbo-frame="_top">
Following link will replace the whole page, not this frame.
</a>

<form action="/messages" data-turbo-frame="navigation">
Submitting form will replace the navigation frame.
</form>
</turbo-frame>

Frame that promotes navigations to Visits

<turbo-frame id="messages" data-turbo-action="advance">
<a href="/messages?page=2">Advance history to next page</a>
<a href="/messages?page=2" data-turbo-action="replace">Replace history with next page</a>
</turbo-frame>

Frame that will get reloaded with morphing during page refreshes & when they are explicitly reloaded with .reload()

<turbo-frame id="my-frame" refresh="morph" src="/my_frame">
</turbo-frame>

Attributes, properties, and functions

The <turbo-frame> element is a custom element with its own set of HTML attributes and JavaScript properties.

HTML Attributes

<turbo-frame id="recursive" recurse="composer" src="recursive.html">
</turbo-frame>

And recursive.html contains:

<turbo-frame id="recursive">
<turbo-frame id="composer">
<a href="frames.html">Link</a>
</turbo-frame>
</turbo-frame>

When Link navigates back to frames.html, Turbo needs to find the frame with ID composer in the response to update the current composer frame. Since there’s no such frame in frames.html directly, Turbo finds the frame with recurse="composer", activates it to load its src (recursive.html), then searches for and extracts the composer frame from that loaded content to update the original frame.

Properties

All <turbo-frame> elements can be controlled in JavaScript environments through instances of the FrameElement class.

Functions

Next: Streams