_source/reference/frames.md
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>
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>
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>
<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>
<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>
<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>
<turbo-frame id="my-frame" refresh="morph" src="/my_frame">
</turbo-frame>
The <turbo-frame> element is a custom element with its own set of HTML
attributes and JavaScript properties.
src accepts a URL or path value that controls navigation
of the element
loading has two valid enumerated values: "eager" and "lazy". When
loading="eager", changes to the src attribute will immediately navigate
the element. When loading="lazy", changes to the src attribute will defer
navigation until the element is visible in the viewport. The default value is eager.
busy is a boolean attribute toggled to be present when a
<turbo-frame>-initiated request starts, and toggled false when the request
ends
disabled is a boolean attribute that prevents any navigation when
present
target refers to another <turbo-frame> element by ID to be navigated when
a descendant <a> is clicked. When target="_top", navigate the window.
complete is a boolean attribute whose presence or absence indicates whether
or not the <turbo-frame> element has finished navigating.
recurse allows the <turbo-frame> to load content that contains another nested
frame. recurse refers to another <turbo-frame> element by ID, present in the
frame's loaded contents. This can be used when Turbo needs to extract frame content
from a response that doesn't contain the target frame directly, but contains another
frame that can load the target frame.
For example, imagine /frames.html contains:
<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.
autoscroll is a boolean attribute that controls whether or not to scroll
a <turbo-frame> element (and its descendant <turbo-frame> elements) into
view after loading. Control the scroll's vertical alignment by setting the
data-autoscroll-block attribute to a valid Element.scrollIntoView({ block:
"..." }) value: one of "end", "start", "center",
or "nearest". When data-autoscroll-block is absent, the default value is
"end". Control the scroll's behavior by setting the
data-autoscroll-behavior attribute to a valid Element.scrollIntoView({
behavior:
"..." }) value: one of "auto", or "smooth".
When data-autoscroll-behavior is absent, the default value is "auto".All <turbo-frame> elements can be controlled in JavaScript environments
through instances of the FrameElement class.
FrameElement.src controls the pathname or URL to be loaded. Setting the src
property will immediately navigate the element. When FrameElement.loaded is
set to "lazy", changes to the src property will defer navigation until the
element is visible in the viewport.
FrameElement.disabled is a boolean property that controls whether or not the
element will load
FrameElement.loading controls the style (either "eager" or "lazy") that
the frame will loading its content.
FrameElement.loaded references a Promise instance that resolves once the
FrameElement's current navigation has completed.
FrameElement.complete is a read-only boolean property set to true when the
FrameElement has finished navigating and false otherwise.
FrameElement.autoscroll controls whether or not to scroll the element into
view once loaded
FrameElement.isActive is a read-only boolean property that indicates whether
or not the frame is loaded and ready to be interacted with
FrameElement.isPreview is a read-only boolean property that returns true
when the document that contains the element is a preview.
FrameElement.reload() is a function that reloads the frame element from its src.