Docs Essentials
Turbo Streams
Out of everything Turbo provides, Turbo Streams benefit the most from a tight backend integration.
Turbo Laravel offers helper functions, Blade Components, and Model traits to generate Turbo Streams. On form submissions, Turbo adds a new MIME type to the HTTP Accept header (Accept: text/vnd.turbo-stream.html, ...). This is a signal to the backend that we can return a Turbo Stream response for that form submission instead of an HTML document, if we want to.
Here's an example of a route handler detecting and returning a Turbo Stream response to a form submission:
Route::post('posts/{post}/comments', function (Post $post) {
$comment = $post->comments()->create(/** params */);
if (request()->wantsTurboStream()) {
return turbo_stream($comment);
}
return back();
});
The request()->wantsTurboStream() macro added to the request class will check if the request accepts Turbo Streams and return true or false accordingly.
The turbo_stream() helper function may be used to generate streams, but you may also use the response()->turboStream() macro. In these docs, we'll only use the helper function, but you may use either one.
Here's what the HTML response will look like:
<turbo-stream action="append" target="comments">
<template>
<div id="comment_123">
<p>Hello, World</p>
</div>
</template>
</turbo-stream>
Most of these values were "guessed" based on the conventions we talked about earlier, but you can override most of them, like so:
turbo_stream($comment)->target('post_comments');
This would render the following Turbo Stream:
<turbo-stream action="append" target="post_comments">
<template>
<div id="comment_123">
<p>Hello, World</p>
</div>
</template>
</turbo-stream>
Although it's handy to pass a model instance to the turbo_stream() function (which will be used to decide the default values of the Turbo Stream response based on the model's current state), sometimes you may want to build a Turbo Stream response manually:
turbo_stream()
->target('comments')
->action('append')
->view('comments.partials.comment', ['comment' => $comment]);
There are also shorthand methods you may use:
turbo_stream()->append($comment);
turbo_stream()->prepend($comment);
turbo_stream()->before($comment);
turbo_stream()->after($comment);
turbo_stream()->replace($comment);
turbo_stream()->update($comment);
turbo_stream()->remove($comment);
turbo_stream()->refresh();
You may pass an Eloquent model instance to all of these shorthand methods, except refresh. The model will be used to figure out things like the target and the view, and it will also be passed to the view.
For a model App\Models\Comment, the convention says that the view is located at resources/views/comments/_comment.blade.php. Based on the model's class basename, it will figure out the name of the variable that the view should depend on, which would be $comment in this case, so it would pass the model instance down to the view automatically. For that reason, when using the convention (which is optional), the model's view must only depend on the model instance (no globals or other locals without defaults).
Alternatively, you may also pass strings to the shorthand stream builders, which will be used as the target, and an optional content string, which will be rendered instead of a partial, for instance:
turbo_stream()->append('statuses', __('Comment created!'));
The optional content parameter expects either a string, a view instance, or an instance of Laravel's Illuminate\Support\HtmlString, so you could do something like:
turbo_stream()->append('some_dom_id', view('greetings', [
'name' => 'Tester',
]));
Or more explicitly by passing an instance of the HtmlString as content:
use Illuminate\Support\Facades\Blade;
use Illuminate\Support\HtmlString;
turbo_stream()->append('statuses', new HtmlString(
Blade::render('<div>Hello, {{ $name }}</div>', ['name' => 'Tony'])
));
Which will result in a Turbo Stream like this:
<turbo-stream target="statuses" action="append">
<template>
<div>Hello, Tony</div>
</template>
</turbo-stream>
For both the before and after methods, you need an additional call to specify the view template you want to insert, since the given model/string will only be used as the target, something like:
turbo_stream()
->before($comment)
->view('comments.partials.flash_message', [
'message' => __('Comment created!'),
]);
Just like the other shorthand stream builders, you may also pass an optional content string or HtmlString instance to the before and after shorthands. When doing that, you don't need to specify the view.
turbo_stream()->before($comment, __('Oh, hey!'));
You can read more about Turbo Streams in the Turbo Handbook.
As mentioned earlier, passing a model to the turbo_stream() helper (or the shorthand Turbo Stream builders) will pre-fill the pending response object with some defaults based on the model's state.
It will build a remove Turbo Stream if the model was just deleted (or trashed, in case it's a soft-deleted model), an append if the model was recently created (you may override the action using the second parameter), and a replace if the model was just updated (you may also change it to update using the second parameter). Here's what overriding looks like:
return turbo_stream($comment, 'append');
Turbo Streams & Morph
Both the update and replace Turbo Stream actions can specify a [method="morph"] attribute, so the action will use DOM morphing instead of the default renderer.
To generate a Turbo Stream with the [method="morph"] attribute, chain the morph() method:
turbo_stream()->replace(dom_id($post, 'comments'), view('comments.partials.comment', [
'comment' => $comment,
]))->morph();
This would generate the following Turbo Stream HTML:
<turbo-stream action="replace" target="comments_post_123" method="morph">
<template>...</template>
</turbo-stream>
And here's the update action version:
turbo_stream()->update(dom_id($post, 'comments'), view('comments.partials.comment', [
'comment' => $comment,
]))->morph();
This would generate the following Turbo Stream HTML:
<turbo-stream action="update" target="comments_post_123" method="morph">
<template>...</template>
</turbo-stream>
Target Multiple Elements
Turbo Stream elements can either have a target with a DOM ID or a targets attribute with a CSS selector to match multiple elements. You may use the *All shorthand methods to set the targets attribute instead of target:
turbo_stream()->appendAll('.comment', 'Some content');
turbo_stream()->prependAll('.comment', 'Some content');
turbo_stream()->updateAll('.comment', 'Some content');
turbo_stream()->replaceAll('.comment', 'Some content');
turbo_stream()->beforeAll('.comment', 'Some content');
turbo_stream()->afterAll('.comment', 'Some content');
turbo_stream()->removeAll('.comment');
With the exception of the removeAll method, the *All methods accept a string of inline content, a View instance (which may be created using Laravel's view() function), or an instance of the HtmlString class as the second parameter.
When creating Turbo Streams using the builders, you may also specify a CSS selector using the targets() (plural) method instead of the target() (singular) version:
turbo_stream()
->targets('.comment')
->action('append')
->view('comments.partials.comment', ['comment' => $comment]);
Turbo Stream Macros
The turbo_stream() function returns an instance of PendingTurboStreamResponse, which is macroable. This means you can create your own DSL for your custom Turbo Streams. Let's say you always return flash messages from your controllers like so:
class ChirpsController extends Controller
{
public function destroy(Request $request, Chirp $chirp)
{
$this->authorize('delete', $chirp);
$chirp->delete();
if ($request->wantsTurboStream()) {
return turbo_stream([
turbo_stream($chirp),
turbo_stream()->append('notifications', view('layouts.notification', [
'message' => __('Chirp deleted.'),
])),
]);
}
// ...
}
}
Chances are you're going to return flash messages from all your controllers, so you could create a custom macro like so:
class AppServiceProvider extends ServiceProvider
{
public function boot()
{
PendingTurboStreamResponse::macro('flash', function (string $message) {
return $this->append('notifications', view('layouts.notification', [
'message' => $message,
]));
});
}
}
You could then rewrite that controller like so:
class ChirpsController extends Controller
{
public function destroy(Request $request, Chirp $chirp)
{
$this->authorize('delete', $chirp);
$chirp->delete();
if ($request->wantsTurboStream()) {
return turbo_stream([
turbo_stream($chirp),
turbo_stream()->flash(__('Chirp deleted.')),
]);
}
// ...
}
}
Turbo Streams Combo
You may combine multiple Turbo Streams in a single response like so:
return turbo_stream([
turbo_stream()
->append($comment)
->target(dom_id($comment->post, 'comments')),
turbo_stream()
->update(dom_id($comment->post, 'comments_count'), view('posts.partials.comments_count', [
'post' => $comment->post,
])),
]);
Although this is a valid option, it might feel like too much work for a controller. If that's the case, you may use Custom Turbo Stream Views.
Custom Turbo Stream Views
Although combining Turbo Streams in a single response right there in the controller is a valid option, it may feel like too much work for a controller. If that's the case, you may want to extract the Turbo Streams to a Blade view and respond with that instead:
return turbo_stream_view('comments.turbo.created_stream', [
'comment' => $comment,
]);
Similar to the turbo_stream() helper function and the Response::turboStream() macro, you may prefer using the Response::turboStreamView() macro instead. It works the same way.
Here's an example of a more complex custom Turbo Stream view:
@include('layouts.turbo.flash_stream')
<turbo-stream target="@domid($comment->post, 'comments')" action="append">
<template>
@include('comments.partials.comment', ['comment' => $comment])
</template>
</turbo-stream>
Remember, these are Blade views, so you have the full power of Blade at your disposal. In this example, we're including a shared Turbo Stream partial that appends any flash messages we may have. That layouts.turbo.flash_stream could look like this:
@if (session()->has('status'))
<turbo-stream target="notice" action="append">
<template>
@include('layouts.partials.flash')
</template>
</turbo-stream>
@endif
Similar to the <x-turbo::frame> Blade component, there's also a <x-turbo::stream> Blade component that can simplify things a bit. It follows the same convention for figuring out the DOM ID when you pass a model instance or an array as the target attribute. When using the component version, there's no need to add the <template> wrapper to the Turbo Stream tag, as the component adds it for you. So, the same example would look something like this:
@include('layouts.turbo.flash_stream')
<x-turbo::stream :target="[$comment->post, 'comments']" action="append">
@include('comments.partials.comment', ['comment' => $comment])
</x-turbo::stream>
I hope you can see how powerful this can be for reusing views.
Custom Actions
You may also use the <x-turbo::stream> Blade component for your custom actions:
<x-turbo::stream action="console_log" value="Hello World" />
Custom actions are only supported from Blade views. You cannot return them from controllers using the pending Turbo Stream builder.