Configuration of Matrix Fields for Flexible Content in Craft CMS
Matrix Field is the main tool for page builder functionality without third-party plugins. The editor adds blocks of different types in arbitrary order, the developer renders them via switch in Twig.
When to Use Matrix
Matrix is suitable for:
- Page bodies with mixed content (text + images + quotes + CTA)
- Homepage sections (hero + features + testimonials + pricing)
- FAQ blocks, timelines, product features
Matrix is excessive for:
- Simple lists of uniform elements → use separate Channel
- One type of content repeating several times → use Table field
Designing Matrix Block Types
Example for pageBody field on corporate website:
pageBody (Matrix)
├── richText
│ └── content: Redactor (formatting: all)
│
├── image
│ ├── image: Assets (single)
│ ├── caption: Plain Text
│ ├── alignment: Dropdown (left/center/right/full)
│ └── linkUrl: URL (optional)
│
├── imageText
│ ├── image: Assets (single)
│ ├── imagePosition: Lightswitch (image left/right)
│ ├── heading: Plain Text
│ ├── text: Redactor (limited)
│ └── buttonLabel + buttonUrl: Plain Text + URL
│
├── gallery
│ ├── images: Assets (multiple)
│ ├── columns: Dropdown (2/3/4)
│ └── caption: Plain Text
│
├── codeBlock
│ ├── language: Dropdown (php/js/python/bash/json/yaml)
│ └── code: Plain Text (monospace)
│
├── testimonial
│ ├── quote: Plain Text (textarea)
│ ├── author: Plain Text
│ ├── role: Plain Text
│ └── avatar: Assets (single)
│
├── stats
│ └── items (Matrix nested or Table):
│ ├── value: Plain Text
│ ├── label: Plain Text
│ └── icon: Assets
│
└── cta
├── heading: Plain Text
├── text: Plain Text
├── primaryLabel + primaryUrl: Plain Text + URL
└── secondaryLabel + secondaryUrl: Plain Text + URL (optional)
Twig Matrix Rendering
{# templates/_components/matrix-content.twig #}
{% for block in entry.pageBody.all() %}
<div class="content-block content-block--{{ block.type.handle }}" id="block-{{ block.id }}">
{% switch block.type.handle %}
{% case 'richText' %}
<div class="prose max-w-prose mx-auto">
{{ block.content }}
</div>
{% case 'image' %}
{% set img = block.image.one() %}
{% if img %}
<figure class="image-block align-{{ block.alignment }}">
{% if block.linkUrl %}
<a href="{{ block.linkUrl }}" target="_blank" rel="noopener">
{% endif %}
<img
src="{{ img.getUrl({ width: 1200 }) }}"
alt="{{ img.alt ?? '' }}"
loading="lazy"
width="{{ img.width }}"
height="{{ img.height }}">
{% if block.linkUrl %}</a>{% endif %}
{% if block.caption %}
<figcaption>{{ block.caption }}</figcaption>
{% endif %}
</figure>
{% endif %}
{% case 'imageText' %}
<section class="image-text {{ block.imagePosition ? 'image-right' : 'image-left' }}">
<div class="image-text__image">
{% set img = block.image.one() %}
{% if img %}
<img src="{{ img.getUrl({ width: 600 }) }}" alt="{{ img.alt ?? '' }}" loading="lazy">
{% endif %}
</div>
<div class="image-text__content">
{% if block.heading %}<h2>{{ block.heading }}</h2>{% endif %}
<div class="prose">{{ block.text }}</div>
{% if block.buttonLabel and block.buttonUrl %}
<a href="{{ block.buttonUrl }}" class="btn">{{ block.buttonLabel }}</a>
{% endif %}
</div>
</section>
{% case 'codeBlock' %}
<pre class="code-block" data-language="{{ block.language }}">
<code class="language-{{ block.language }}">{{ block.code | escape }}</code>
</pre>
{% case 'testimonial' %}
<blockquote class="testimonial">
<p>{{ block.quote }}</p>
<footer>
{% set avatar = block.avatar.one() %}
{% if avatar %}
<img src="{{ avatar.getUrl({ width: 80, height: 80, mode: 'crop' }) }}" alt="{{ block.author }}">
{% endif %}
<cite>
<strong>{{ block.author }}</strong>
{% if block.role %}<span>{{ block.role }}</span>{% endif %}
</cite>
</footer>
</blockquote>
{% case 'cta' %}
<div class="cta-block">
{% if block.heading %}<h2>{{ block.heading }}</h2>{% endif %}
{% if block.text %}<p>{{ block.text }}</p>{% endif %}
<div class="cta-block__buttons">
{% if block.primaryLabel %}
<a href="{{ block.primaryUrl }}" class="btn btn--primary">{{ block.primaryLabel }}</a>
{% endif %}
{% if block.secondaryLabel %}
<a href="{{ block.secondaryUrl }}" class="btn btn--secondary">{{ block.secondaryLabel }}</a>
{% endif %}
</div>
</div>
{% endswitch %}
</div>
{% endfor %}
Performance: Eager Loading
Matrix blocks with Assets and Relations create N+1 queries without eager loading:
{# Bad — N+1 for each block with image #}
{% for block in entry.pageBody.all() %}
{# Good — preload all relationships #}
{% set blocks = entry.pageBody
.with(['image', 'images', 'avatar'])
.all() %}
Limiting Block Types via Entry Type
Different Entry Types can use different sets of Matrix blocks, but the Matrix field itself is shared. This is implemented via JavaScript in CP (conditional visibility), but not at data level.
Configuration of Matrix with 5–8 block types and templates takes 2–4 days.