Managing complex content in Craft CMS often involves using the powerful Matrix field. While Matrix fields provide incredible flexibility, they can quickly become overwhelming in the Control Panel (CP) when an entry contains dozens of blocks. By default, Craft CMS expands these blocks, which can lead to a 'scroll-fest' for your content editors. To improve the author experience (AX), many developers look for a way to collapse Matrix rows by default.

In this guide, we will explore how to implement a solution that ensures your Matrix blocks are tucked away neatly when a page loads, allowing editors to focus on the specific sections they need to update.

Why Collapse Matrix Blocks by Default?

As a site grows, your Matrix fields might include various block types—from simple text areas to complex image galleries and nested entries. When an entry has 10 or 20 blocks, the edit screen becomes incredibly long. This clutter makes it difficult for authors to:

  1. Get a bird's-eye view of the page structure.
  2. Reorder blocks efficiently using drag-and-drop.
  3. Locate specific content quickly.

By forcing these blocks into a collapsed state upon page load, you provide a cleaner, more organized interface. This is a hallmark of a high-quality Craft CMS build where the developer has prioritized the needs of the end-user.

The JavaScript Solution

Since Craft CMS does not currently have a native 'Collapse by Default' setting within the Matrix field configuration, we can achieve this behavior by injecting a small piece of JavaScript into the Control Panel.

The following script targets all elements with the .matrixblock class, adds the collapsed class to them, and uses the internal Craft.MatrixInput API to ensure the system remembers this state.

$('.matrixblock').each(function() {
    $(this).addClass('collapsed');
    Craft.MatrixInput.rememberCollapsedBlockId($(this).data('id'));
});

How the Code Works

  • $('.matrixblock').each(...): This iterates through every Matrix block currently rendered on the page.
  • $(this).addClass('collapsed'): This adds the CSS class that Craft uses to visually hide the block's fields and show only the header.
  • Craft.MatrixInput.rememberCollapsedBlockId(...): This is a crucial step. Craft CMS tracks which blocks are collapsed in the user's browser storage. By calling this method, we ensure that the UI state remains consistent and doesn't 'flicker' or revert unexpectedly.

Implementing the Injection

You cannot simply paste this code into your frontend templates; it must be executed within the context of the Craft Control Panel. There are two primary ways to do this:

1. Using a Custom Module or Plugin

If you are already using a custom module for your project (which is recommended for most Craft sites), you can use the cp.addJs method. You would typically place this logic within your module's init() method, ensuring it only runs during CP requests.

use craft\events\TemplateEvent;
use craft\web\View;
use yii\base\Event;

Event::on(
    View::class,
    View::EVENT_BEFORE_RENDER_TEMPLATE,
    function (TemplateEvent $event) {
        if (Craft::$app->getRequest()->getIsCpRequest()) {
            $js = <<<'JS'
                $('.matrixblock').each(function() {
                    $(this).addClass('collapsed');
                    Craft.MatrixInput.rememberCollapsedBlockId($(this).data('id'));
                });
JS;
            Craft::$app->getView()->registerJs($js);
        }
    }
);

2. Using the Control Panel JS Plugin

For those who prefer a more plug-and-play approach, the "Control Panel JS" plugin allows you to add custom JavaScript directly through the Craft settings. This is ideal for smaller projects where setting up a full PHP module might be overkill. Simply install the plugin and paste the snippet into the provided text area.

Improving the UI with "Expand/Collapse All"

While collapsing blocks by default is a great start, you might also want to give users the ability to toggle all blocks at once. While Craft has introduced some UI improvements in recent versions, you can manually add a 'Toggle All' button to the Matrix header via JavaScript.

This provides the best of both worlds: a clean start (all collapsed) and the ability to open everything if the editor needs to perform a global search-and-replace or audit the content.

Considerations for Craft CMS 5

It is important to note that Craft CMS 5 introduced significant changes to how Matrix fields work. In Craft 5, Matrix blocks are now technically entries. This change improved data consistency and reusability, but it also changed the DOM structure of the Control Panel.

If you are using Craft 5, the CSS selectors (like .matrixblock) may differ. You should inspect the source code of your CP and update your selectors accordingly. Additionally, Craft 5 has enhanced the native UI for managing large sets of entries, so you may find that the built-in 'Table' or 'Cards' view modes for Matrix fields alleviate the need for this custom JavaScript entirely.

Frequently Asked Questions

Does this affect performance?

No. This script runs on the client side after the page has loaded. Since it only manipulates the CSS classes of elements already present in the DOM, the performance impact is negligible.

Will this collapse blocks on the frontend?

No. This script only targets the Craft Control Panel CSS classes. Your frontend rendering remains entirely controlled by your Twig templates and will not be affected.

Can I target specific Matrix fields only?

Yes. If you only want to collapse a specific field, you can refine your jQuery selector. Instead of targeting all .matrixblock elements, you can target blocks within a specific container ID, such as $('#fields-myFieldHandle .matrixblock').

Wrapping Up

Customizing the Craft CMS Control Panel is one of the best ways to provide a premium experience for your clients. By implementing a 'collapse by default' behavior for Matrix rows, you reduce cognitive load for authors and make content management a much smoother process. Whether you choose to use a custom module or a simple utility plugin, this small tweak goes a long way in professionalizing your Craft CMS builds.

Always remember to test your JavaScript injections after major Craft updates to ensure that class names and internal APIs have not changed!