Matrix Fields

Matrix fields allow you to create multiple blocks of content within a single field.

# Settings

Matrix fields have the following settings:

  • Configuration – This is where you configure which block types should be available to your Matrix field, and which sub-fields each of those block types should have.
  • Min Blocks – The minimum number of blocks that can be created within the field. (Default is no limit.)
  • Max Blocks – The maximum number of blocks that can be created within the field. (Default is no limit.)

# The Field

On a fresh entry, Matrix fields will just show a group of buttons – one for each of the Block Types you created in the field’s settings:

An empty Matrix field’s block types

When you click on one of those buttons, a new block will be created. The Block Type’s name will be shown in the block’s title bar, and each of the Block Type’s fields will be present within the body of the block:

A newly-added Quote block

You can add as many blocks to your Matrix field as you’d like—or at least as many as the field’s Min Blocks and Max Blocks settings allow.

Each block has a settings menu that reveals additional things you can do with the block:

A Matrix block’s action menu

If multiple blocks are selected, the Collapse/Expand, Disable/Enable, and Delete options will apply to each of those selected.

You can collapse Matrix blocks by choosing the Collapse menu option or by double-clicking on a block’s title bar. When a block is collapsed, its title bar will show a preview of its content so you can still identify which block it is.

Blocks can also be reordered by dragging the “Move” icon (

Drag-and-drop handle icon
) at the end of the block’s title bar. If multiple blocks are selected, all the selected blocks will be going along for the ride.

You can quickly select all blocks by selecting one and pressing Ctrl/ + A, or selecting a range of blocks starting with the first and then Shift-clicking the last.

# Development

# Querying Elements with Matrix Fields

When querying for elements that have a Matrix field, you can filter the results based on the Matrix field data using a query param named after your field’s handle.

Possible values include:

Value Fetches elements…
':empty:' that don’t have any Matrix blocks.
':notempty:' that have at least one Matrix block.
100 that have a Matrix block with an ID of 100.
[100, 200] that have Matrix blocks with IDs of 100 or 200.
a MatrixBlock (opens new window) object that have the Matrix block.
an array of MatrixBlock (opens new window) objects that have the Matrix blocks.
{# Fetch entries with a Matrix block #}
{% set entries = craft.entries()
  .myFieldHandle(':notempty:')
  .all() %}
{# Fetch entries with Matrix block ID 100 or 200 #}
{% set entries = craft.entries()
  .myFieldHandle([100, 200])
  .all() %}

# Working with Matrix Field Data

If you have an element with a Matrix field in your template, you can access its blocks using your Matrix field’s handle:

{% set query = entry.myFieldHandle %}

That will give you a Matrix block query, prepped to output all the enabled blocks for the given field.

To loop through all the blocks, call all() (opens new window) and loop over the results:

{% set blocks = entry.myFieldHandle.all() %}
{% if blocks|length %}
  <ul>
    {% for block in blocks %}
      <!-- ... -->
    {% endfor %}
  </ul>
{% endif %}

All the code you put within the for-loop will be repeated for each Matrix block in the field. The current block will get set to that block variable we’ve defined, and it will be a craft\elements\MatrixBlock (opens new window) model.

Here’s an example of what the template might look like for a Matrix field with four block types (Heading, Text, Image, and Quote). We can determine the current block type’s handle by checking block.type (craft\elements\MatrixBlock::getType() (opens new window)).

{% for block in entry.myFieldHandle.all() %}
  {% if block.type == "heading" %}
    <h3>{{ block.heading }}</h3>
  {% elseif block.type == "text" %}
    {{ block.text|markdown }}
  {% elseif block.type == "image" %}
    {% set image = block.image.one() %}
    {% if image %}
        <img src="{{ image.getUrl('thumb') }}" 
          width="{{ image.getWidth('thumb') }}" 
          height="{{ image.getHeight('thumb') }}" 
          alt="{{ image.title }}"
        >
    {% endif %}
  {% elseif block.type == "quote" %}
    <blockquote>
      <p>{{ block.quote }}</p>
      <cite>{{ block.cite }}</cite>
    </blockquote>
  {% endif %}
{% endfor %}

This code can be simplified using the switch tag.

If you only want the first block, call one() (opens new window) instead of all(), and make sure it returned something:

{% set block = entry.myFieldHandle.one() %}
{% if block %}
  <!-- ... -->
{% endif %}

If you only want to know the total number of blocks, call count() (opens new window).

{% set total = entry.myFieldHandle.count() %}
<p>Total blocks: <strong>{{ total }}</strong></p>

If you just need to check if blocks exist (but don’t need to fetch them), you can call exists() (opens new window):

{% if entry.myFieldHandle.exists() %}
  <p>There are blocks!</p>
{% endif %}

You can set parameters on the Matrix block query as well. For example, to only fetch blocks of type text, set the type param:

{% set blocks = clone(entry.myFieldHandle)
  .type('text')
  .all() %}

It’s always a good idea to clone the Matrix query using the clone() function before adjusting its parameters, so the parameters don’t have unexpected consequences later on in your template.

# Saving Matrix Fields

If you have an element form, such as an entry form (opens new window), that needs to contain a Matrix field, you will need to submit your field value in this format:

- sortOrder
- blocks
  - <BlockID_1>
    - type
    - fields
      - <FieldHandle_1>
      - <FieldHandle_2>
  - <BlockID_2>
    - type
    - fields
      - ...

sortOrder should be submitted as an array of all the block IDs you wish to persist (as well as any new block IDs), in the order they should be saved.

If you want all existing blocks to persist in the same order they are currently in, then use this template to define your sortOrder array:

{% if entry is defined %}
  {% for blockId in clone(entry.myFieldHandle).anyStatus().ids() %}
    {{ hiddenInput('fields[myFieldHandle][sortOrder][]', blockId) }}
  {% endfor %}
{% endif %}

All of your block data should be nested under blocks, indexed by their IDs. Each block must submit its type and custom field data nested under a fields array.

Here’s how you can output form fields for existing blocks, for a Matrix field with two block types (text and image):

{% if entry is defined %}
  {% for block in entry.myFieldHandle.all() %}
    {# Prefix the block's input names with `fields[myFieldHandle][blocks][<BlockID>]` #}
    {% namespace "fields[myFieldHandle][blocks][#{block.id}]" %}
      {{ hiddenInput('type', block.type) }}
      {% switch block.type %}
        {% case 'text' %}
          <textarea name="fields[<TextFieldHandle>]">
            {{- block.<TextFieldHandle>|raw -}}
          </textarea>
        {% case 'image' %}
          {% set images = block.<AssetsFieldHandle>.all() %}
          {% if images|length %}
            <ul>
              {% for image in block.<AssetsFieldHandle>.all() %}
                <li>
                  {{ image.getImg({ width: 100, height: 100 }) }}
                  {{ hiddenInput('fields[<AssetsFieldHandle>][]', image.id) }}
                </li>
              {% endfor %}
            </ul>
          {% endif %}
      {% endswitch %}
    {% endnamespace %}
  {% endfor %}
{% endif %}

Outputting form fields for existing blocks is completely optional. As long as the block IDs are listed in the sortOrder array, they will persist even if they are missing from the form data.

To show a “New Block” form, first come up with a temporary ID for the block, prefixed with new:. For example, new:1, new:2, etc.

Append the temporary ID to the sortOrder array, and use it when outputting the block’s form inputs.

You’ll probably want to include a JavaScript-powered component to the field that appends new block inputs to the form. New blocks should have an “ID” of new:X, where X is any number that is unique among all new blocks for the field.

For example, the first new block that is added to the form could have an “ID” of new:1, so its type input name would end up looking like this:

<input type="hidden" name="fields[myFieldHandle][new:1][type]" value="text" />

Then define the form inputs for any additional blocks that should be appended to the input.

{{ hiddenInput('fields[myFieldHandle][sortOrder][]', 'new:1') }}

{# Prefix the block's input names with `fields[myFieldHandle][blocks][new:1]` #}
{% namespace "fields[myFieldHandle][blocks][new:1]" %}
  {{ hiddenInput('type', 'text') }}
  <textarea name="fields[<TextFieldHandle>]"></textarea>
{% endnamespace %}

# See Also