Radical Design Course by Jack McDade

From the creator of Statamic

Learn how to make your websites standout and be remembered.

Just exceptional. Thank you so much, Jack, you smashed it.

— Hugo, Developer

Partial Tag

Partials are reusable views that may find themselves in any number of other layouts, templates, and other partials.

Overview

You can use any view as a partial by using this here partial tag.

// This will import /resources/views/blog/_card.antlers.html
{{ partial:blog/card }}
// This will import /resources/views/blog/_card.antlers.html
<s:partial:blog/card />
Best Practice

We recommend prefixing any views intended to be only used as partials with an underscore, _like-this.antlers.html and reference them `{{ partial:like-this }}. The underscore is not necessary in the partial tag definition.

Passing Data

You can pass additional data into a partial via on-the-fly parameters. The parameter name will become a variable inside the partial. The only reserved parameter is src, so you can name your variables just about anything.

{{ partial:list header="favorite ice cream flavors" :items="flavors" }}
 
// Inside `list.antlers.html`
<h2>These are my {{ header }}</h2>
{{ items | ul }}
<s:partial:list
header="favorite ice cream flavors"
:items="$flavors"
/>
{{-- Inside `list.blade.php` --}}
 
<h2>These are my {{ $header }}</h2>
{!! Statamic::modify($items)->ul() !!}
<h2>These are my favorite ice cream flavors</h2>
<ul>
<li>Chocolate Chip Cookie Dough</li>
<li>Mint Chocolate Chip</li>
<li>Neon Mind Melter</li>
</ul>

Note that the :items parameter is prefixed by a colon, meaning it will pass the value of a flavors variable, if it exists.

Best Practice

To set default values for parameters inside your partials, you can add YAML front-matter to the top of your Antlers partials.

In the example below, the partial has two front-matter variables (author and image). When the partial is called, the author parameter is provided. When the partial is outputted, the author parameter is used, and the value for the image variable falls back to the partial's front-matter.

{{ partial:card author="David Hasselhoff" }}
---
author: Jack McDade
image: https://example.com/placeholder.png
---
 
<img src="{{ view:image }}">
<p>Written by {{ view:author }}</p>
<s:partial:card author="David Hasselhoff" />
@frontmatter([
'author' => 'Jack McDade',
'image' => 'https://example.com/placeholder.png',
])
 
<img src="{{ $view['image'] }}">
<p>Written by {{ $view['author'] }}</p>
<img src="https://example.com/placeholder.png"> <!-- No image was provided, so falling back to the front-matter. -->
<p>Written by David Hasselhoff</p> <!-- Author parameter provided, so using that. -->

This technique is preferrable over defining custom variables inside your partial.

Slots

Sometimes you might need to pass a large chunk of content into a partial. Jamming a bunch of HTML through a parameter would be like trying to shove a pizza through a donut. A hilarious YouTube video but a bad idea on a Friday night.

The solution is to use the partial tag as a pair. Everything inside will be passed into the partial in the {{ slot }} variable.

// Your main view
{{ partial:modal title="Confirmation" }}
<div class="flex items-center">
<img src="/img/warning.svg" />
<p>Are you sure you want to delete your entire collection of WWE wrestling figures?</p>
</div>
{{ /partial:modal }}
 
// _modal.antlers.html
<div class="bg-white rounded shadow">
<h2 class="p-2 border-b">{{ title }}</h2>
{{ slot }}
<button @click="confirm" class="button">Do it</button>
</div>
// Your main view
<s:partial:modal title="Confirmation">
<div class="flex items-center">
<img src="/img/warning.svg" />
<p>Are you sure you want to delete your entire collection of WWE wrestling figures?</p>
</div>
</s:partial:modal>
 
// _modal.blade.php
<div class="bg-white rounded shadow">
<h2 class="p-2 border-b">{{ $title }}</h2>
{!! $slot !!}
<button @click="confirm" class="button">Do it</button>
</div>
<div class="bg-white rounded shadow">
<h2 class="p-2 border-b">Confirmation</h2>
<div class="flex items-center">
<img src="/img/warning.svg" />
<p>Are you sure you want to delete your entire collection of WWE wrestling figures?</p>
</div>
<button @click="confirm" class="button">Do it</button>
</div>

Conditional Rendering

You can render a partial only if a condition is met.

{{ partial:components/subtitle :when="subtitle" }}
{{ subtitle }}
{{ /partial:components/subtitle }}
<s:partial:components/subtitle :when="isset($subtitle)">
{{ $subtitle }}
</s:partial:components/subtitle>

Also supports the converse using :unless.

If you haven't read up on views yet, you should. It's considered fundamental knowledge, like knowing that seals are just dog mermaids. 🐕 🧜‍♀️

You may also be interested in the partial:exists or partial:if_exists tags.

Parameters

src

string

You can pass the name of the partial with a parameter instead of tag argument. Example: src="cards/author_bio" or :src="var_name".

when

string

Render a partial only if a condition is met.

unless

string

The converse of when.

*

mixed

Any parameter you create will be passed through to the partial as a variable.

Docs feedback

Submit improvements, related content, or suggestions through Github.

Betterify this page →