<p>Fabien Potencier, the main developer of the Twig templating language <a href="https://github.com/twigphp/Twig/issues/1697">answered the question</a> like so:</p>

<blockquote>
  <ul>
  <li>Macros: reusable markup across a lot of templates</li>
  <li>Includes: part of "pages" that are extracted for readability and reusability</li>
  </ul>
</blockquote>

<p>The reason for this, as far as I understand, is that you can only use the <code>include</code> tag to render the complete file containing your partial. Whereas the <code>macro</code> tag allows to render a partial from a file with multiple macros / partials in it.</p>

<p>That being said, you are totally right in saying that both basically do the same thing. You can pass in variables, use them recursively, I do not know of a single thing one can do that the other can’t. Even performance shouldn’t be different really, at least within the context of Craft, as your Twig code gets compiled down to PHP and will then be cached.</p>

<p>What I personally do is to use macros for all the small things, something simple like the following example. I wouldn’t want to create a separate file for every little helper that allows me to keep things DRY.</p>

<pre><code>{% macro icon(iconId) %}
    &lt;svg class="icon icon-{{ iconId }}" role="img" title="{{ iconId }}"&gt;
        &lt;use xlink:href="{{ url('assets/icons/icons.svg#icon-' ~ iconId) }}"&gt;&lt;/use&gt;
    &lt;/svg&gt;
{% endmacro %}
</code></pre>

<p>For larger chunks of code like a partial for a teaser card that I want to reuse throughout the site I’d definitly go with an <code>include</code>. I really want to have one dedicated file for each of these partials, main reason here is that I wouldn’t want any unrelated code in that file as they usually contain quite a lot of code. Another reason might be the better discoverability in the file structure.</p>

<p>Of course I could also setup files with only one macro in them instead. But then I’d end up with a bunch of <code>import</code> tags to load the macro files. So in the end it’s probably only a matter of the more appropriate syntax for each situation.</p>

<p>My project usually end up with between 20 and 100 partials for <code>include</code> tags, but I almost never have more than a single file for the macros.</p>

CC BY-SA 3.0
2016-07-23T16:59:47.160Z
Thanks @carlcs this makes great sense and is explained very well. I also like the SVG icon macro. I might incorporate that one :-)
Terry Upton
CC BY-SA 3.0
2016-07-23T15:46:18.127Z
2016-07-23T18:02:27.877Z
2016-07-23T18:02:27.877Z
carlcs
<p>Is there any guidance or pitfalls/benefits of using one over another? I see that includes can be done more or less the same way a Macro can be done (certainly for simple variable changes).</p>

<p>An example being with a series of social sharing links.
So I currently have the following setup as an include like so;</p>

<pre><code>&lt;ul class="social-list"&gt;
    &lt;li&gt;
        &lt;a href="https://twitter.com//intent/tweet/?text={{ object.title }}&amp;amp;url={{ craft.request.url|url_encode }}&amp;amp;via={{ socialMedia.twitter }}" target="_blank" title="Share on Twitter" class="js-social-share // track-social" data-label="Shared"&gt;
            &lt;svg role="img" class="icon // icon-social  // icon-social--share // icon-twitter"&gt;
            &lt;use xlink:href="/assets/img/icons.svg#share-twitter"&gt;Twitter&lt;/use&gt;
            &lt;/svg&gt;
        &lt;/a&gt;
    &lt;/li&gt;

    &lt;li&gt;
        &lt;a href="https://www.facebook.com/sharer/sharer.php?u={{ craft.request.url|url_encode }}" target="_blank" title="Share on Facebook"  class="js-social-share // track-social" data-label="Shared"&gt;
            &lt;svg role="img" class="icon // icon-social  // icon-social--share // icon-facebook"&gt;
            &lt;use xlink:href="/assets/img/icons.svg#share-facebook"&gt;Facebook&lt;/use&gt;
            &lt;/svg&gt;
        &lt;/a&gt;
    &lt;/li&gt;

    &lt;li&gt;
        &lt;a href="https://plus.google.com/share?url={{ craft.request.url|url_encode }}" target="_blank" title="Share on Google Plus" class="js-social-share // track-social" data-label="Shared"&gt;
            &lt;svg role="img" class="icon // icon-social  // icon-social--share // icon-google-plus" class="js-social-share // track-social" data-label="Shared"&gt;
            &lt;use xlink:href="/assets/img/icons.svg#share-googleplus"&gt;Google Plus&lt;/use&gt;
            &lt;/svg&gt;
        &lt;/a&gt;
    &lt;/li&gt;

    &lt;li&gt;
        &lt;a href="mailto:?Subject={{ object.title }}&amp;amp;Body=I%20saw%20this%20and%20thought%20it%20might%20be%20of%20interest! {{ craft.request.url|url_encode }}" title="Share via Email" class="track-social" data-label="Shared"&gt;
            &lt;svg role="img" class="icon // icon-social  // icon-social--share // icon-share-email"&gt;
            &lt;use xlink:href="/assets/img/icons.svg#share-email"&gt;Email&lt;/use&gt;
            &lt;/svg&gt;
        &lt;/a&gt;
    &lt;/li&gt;
&lt;/ul&gt;
</code></pre>

<p>and then calling the file like so;</p>

<pre><code>{% include '_includes/social-sharing' with { object : product } %}
</code></pre>

<p>But the same could easily be achieved using a Macro. Something I have previously used for something else, where an include would have also worked.</p>

<p>So is there a best case for when to use a Macro or an Include and what would be better in the above instance and why?</p>

<p>Thanks.</p>

CC BY-SA 3.0
2016-07-23T15:56:51.317Z
Yep, I would have used an include for this as well.
carlcs
<templating><best-practice><macro><include>
Macros vs Includes
# Macros vs Includes

(Asked by: username_0 on 2016-07-23)

Is there any guidance or pitfalls/benefits of using one over another? I see that includes can be done more or less the same way a Macro can be done (certainly for simple variable changes).
An example being with a series of social sharing links.
So I currently have the following setup as an include like so;

    
        
            
            Twitter
            
        
    

    
        
            
            Facebook
            
        
    

    
        
            
            Google Plus
            
        
    

    
        
            
            Email
            
        
    


and then calling the file like so;
{% include '_includes/social-sharing' with { object : product } %}

But the same could easily be achieved using a Macro. Something I have previously used for something else, where an include would have also worked.
So is there a best case for when to use a Macro or an Include and what would be better in the above instance and why?
Thanks.

**Tags:** templating, best-practice, macro, include
> **Comments:**
> **username_1**: Yep, I would have used an include for this as well.  

---

## 1 answers

### Answer by username_1 on 2016-07-23. Score: 19 | Accepted answer

Fabien Potencier, the main developer of the Twig templating language answered the question like so:


Macros: reusable markup across a lot of templates
Includes: part of "pages" that are extracted for readability and reusability


The reason for this, as far as I understand, is that you can only use the include tag to render the complete file containing your partial. Whereas the macro tag allows to render a partial from a file with multiple macros / partials in it.
That being said, you are totally right in saying that both basically do the same thing. You can pass in variables, use them recursively, I do not know of a single thing one can do that the other can’t. Even performance shouldn’t be different really, at least within the context of Craft, as your Twig code gets compiled down to PHP and will then be cached.
What I personally do is to use macros for all the small things, something simple like the following example. I wouldn’t want to create a separate file for every little helper that allows me to keep things DRY.
{% macro icon(iconId) %}
    
        
    
{% endmacro %}

For larger chunks of code like a partial for a teaser card that I want to reuse throughout the site I’d definitly go with an include. I really want to have one dedicated file for each of these partials, main reason here is that I wouldn’t want any unrelated code in that file as they usually contain quite a lot of code. Another reason might be the better discoverability in the file structure.
Of course I could also setup files with only one macro in them instead. But then I’d end up with a bunch of import tags to load the macro files. So in the end it’s probably only a matter of the more appropriate syntax for each situation.
My project usually end up with between 20 and 100 partials for include tags, but I almost never have more than a single file for the macros.

> **Comments:**
> **username_0**: Thanks @carlcs this makes great sense and is explained very well. I also like the SVG icon macro. I might incorporate that one :-)  

---

