If you’re like us, you’ve likely built ‘page builder’ fields in Craft CMS using Matrix. But sometimes you need more than a block. We use Super Table to create ‘page sections’ that include some extra settings (like background color, controls for width, etc.). We can then nest a Matrix field to control page blocks within the Page Section (Super Table). This has worked well for us in the past but there's a new, simpler way to achieve this starting in Craft 5.

Upgrading a site from Craft 4 to Craft 5 can seem intimidating. Even more so when your site relies on complex content models like the one I described above. You might think, okay I'll upgrade to Craft 5 and then look into migrating to the newer method in the future. Well, now is the time. Verbb has announced that Super Table has reached end-of-life.  While there is a Craft 5 compatible version available, it won't receive updates. That means now is the perfect time to migrate your Super Table fields to native Matrix fields.

Craft 5 makes the process easy by converting Matrix blocks to entry types automatically during the upgrade. This guide will walk you through the process. We'll cover preparation, the upgrades themselves, and steps to clean up afterward. As you’ll see below, the process is actually quite simple and nothing to stress over!

Preparing for the Upgrade

The first step in any upgrade is preparation. Start by backing up your site’s database. This ensures that you can restore your site to its previous state if anything goes wrong during the upgrade process. We use (and love) DDEV here at Viget, so this guide will be leveraging it. But you can easily adapt the commands if you are not. To create a database backup, run:

It's also essential to familiarize yourself with the Craft 5 Upgrade Guide. This guide provides detailed information on the changes, new features, and potential breaking changes in Craft 5, helping you understand what to expect. It serves as a fantastic set of instructions to get your site upgraded.

The Upgrade Process

Once you're prepared, you can begin the upgrade process. Per the Craft Upgrade Guide, we will update Craft and plugins at the same time. Open your editor and modify your composer.json with the new versions of your plugins. The two for sure we will need to modify are:

Updating Super Table Fields and Templates

With the Matrix blocks converted to entry types, you need to reconfigure any Super Table fields to be Matrix fields.

Update Super Table Fields:

• Browse to Settings > Fields and edit any Super Table fields
• Change the field type from Super Table to Matrix (there will be no content loss when switching from Super Table to Matrix)
• Select the entry type to use (Craft has already created one for you)
• Save the field
• That's it!

At this point, you have removed your dependency on Super Table and have a page builder entirely built with Matrix fields. What were previously Super Table blocks are now a custom Entry Type and what were Matrix blocks are now also Entry Types. This allows you to have nested Matrix within Matrix thanks to Craft’s Entrification plan.

Cleaning Up After the Upgrade

After updating your fields and templates, it's time to clean up. First, uninstall the Super Table plugin. Navigate to Settings > Plugins in the Control Panel to uninstall the plugin. Then remove it from your project by running:

Thoroughly test your site to ensure everything is functioning correctly. Pay close attention to the entry types where you used Super Table fields, confirming that authoring and your front-end work as expected.

Additionally, you can also take this opportunity to clean up your fields and entry types. Craft 5’s reusable fields and entry types give you ample opportunity to consolidate and Craft 5 provides new utilities to make this process as simple as possible.

• fields/auto-merge — Automatically discovers functionally identical fields and merges their uses together.
• fields/merge — Manually merge one field into another of the same type and update uses of the merged field.
• entry-types/merge — Merge one entry type into another and update uses of the merged entry type.

That’s it!

Upgrading from Craft 4 to Craft 5 and transitioning from Super Table is incredibly simple, thanks to Craft 5’s automatic conversion of Matrix blocks to entry types. Super Table will no longer be maintained moving forward, and it's better to switch to the native Craft solution for better long-term support. By following these steps, you can quickly tackle the change and take advantage of the new features and improvements in Craft 5. With careful planning, thorough testing, and a few commands, you’ll have your page builder working again in Craft 5 in no time. Happy upgrading!