Partial Tag

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.

Antlers Blade

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

You can also name your slots using the name parameter.

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.

Related Reading

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