Component Layout with Matrix Fields in Craft CMS: Configuration Guide

Developers often encounter pitfalls with Matrix Field in Craft CMS: either N+1 queries kill the server, or editors ask for 'one more block type'. In one project, a client's 'About' page had 25 blocks, each with an image. Page load took 8 seconds due to 25 separate media queries. After properly configuring eager loading, the time dropped to 1.2 seconds — a 6.7x improvement. With over 50 Craft projects, we've refined an approach where Matrix neither slows down nor frustrates the team.

How to Design Blocks to Avoid Redesigns

In a typical corporate site, the pageBody field contains 6–10 block types. Each block is a micro-structure: text, image, link, quote, code, stats. It's critical to plan the set of fields — adding a field later is harder than removing one. The optimal landing page structure:

pageBody (Matrix) ├── hero │ ├── heading, subheading, backgroundImage, ctaButton ├── richTextContent │ └── content (Redactor) ├── imageWithCaption │ ├── image, caption, alignment ├── twoColumns │ ├── leftContent, rightContent (Redactor) ├── testimonial │ ├── quote, author, role, avatar ├── stats │ └── items (Table field) ├── ctaBanner │ ├── heading, text, buttonLabel, buttonUrl └── codeSnippet ├── language, code 

Use Table fields for lists (stats, pricing) — they are faster than nested Matrix and easier to cache.

Twig Rendering: switch vs include vs component

Most projects use {% switch %} inside a loop — reliable and readable. But with 10+ blocks, the template becomes bulky. An alternative is to extract each block into a separate include. This simplifies maintenance but is marginally slower due to multiple include calls. The optimal approach renders blocks via a component approach with fragment caching.

In our experience, pages with 15+ blocks gain 40–50 ms by including cache tags.

Why N+1 Destroys Performance and How to Avoid It

Without eager loading, each block with an Assets field generates a separate query. For example, an image block searches for the image, a testimonial block for the avatar. If the page has 10 blocks, you get 10 DB queries plus the block list query. The solution is a single with() call: {% set blocks = entry.pageBody.with(['image', 'avatar', 'backgroundImage']).all() %}.

For blocks containing nested Matrix (e.g., tabs with inner content), use .with()['subMatrixField.childField'] — Craft supports deep eager loading. Full details in the official Craft CMS documentation.

What to Do If Matrix Slows the Control Panel

A Matrix with 50+ blocks in CP is a common nightmare. The reason: each block renders its fields. The solution is to fragment the matrix into multiple fields: separate Matrix for 'header', 'body', and 'footer'. Alternatively, use Neo Field by McDowell — an analog supporting nesting, though at $99 cost.

Tool Selection: When to Use Matrix, Neo, Table

Matrix is best for 80% of projects. Neo is worth it only for more than two levels of nesting. Table and SuperTable are for tabular data.

Block Caching Strategies for Matrix

Matrix blocks break page caching without a strategy. The solution is to cache each block separately with tags. In Twig:

{% cache globally using key 'block-' ~ block.id tags 'matrixBlock:' ~ block.id %} {% include 'matrix/_' ~ block.type.handle %} {% endcache %} 

When a block is modified, Craft invalidates only its cache. For static blocks (richText), cache for a day; for media, for an hour.

pageBody (Matrix): - hero (heading, subheading, backgroundImage, ctaButton) - richTextContent (content Redactor) - imageWithCaption (image, caption, alignment) - twoColumns (leftContent, rightContent Redactor) - testimonial (quote, author, role, avatar) - stats (items Table field) - ctaBanner (heading, text, buttonLabel, buttonUrl) - codeSnippet (language, code)