Grouping replicator sets in Statamic

Grouping replicator sets in Statamic

Published: April 23, 2021

Updated: March 8, 2022






In our quest to build highly customizable websites for customers we stumble in a lot of roadblocks. Giving the client the power to edit the content without breaking the website is one of our goals at Lucky Media.

Luckily we discovered Statamic, which is a flat-file CMS that runs as a Laravel package and you can customize it in every way possible. It comes battery included, but you can always customize it to your own needs because it's built as a Laravel package.

Just recently, we had a client with a very complex website and with as many as 90+ pages. The client builds every page with the help of ready to use blocks that we made available from the CP. If you already use Statamic as a developer, you know the current limitation of the Replicator Field and large sets. If you include all the sets then you end up with a very large list of sets which is extremely difficult to navigate. In this post we will talk about how to group your sets in a replicator field.

Here is a quick picture of what we saw before using the new technique for grouping them:

In our project we had roughly 40+ sets and the above picture is a bit hard to read through.

So how can we group all of this? Natively Statamic doesn't support this yet although an idea was already submitted at the ideas repo . Until there is an official way to group sets, lets take a look at our solution.

To save some time, I will assume you already have a Statamic project running, in our case we use Tailwind CSS for styling but you are free to use anything you want.

In the page blueprint we have the following configuration:

title: Pages
    display: Main
        handle: title
          type: text
          required: true
            - required
        handle: blocks
          collapse: false
          display: Blocks
          type: replicator
          icon: replicator
          listable: hidden
    display: Sidebar
        handle: slug
          type: slug
          required: true
          localizable: true
            - required

As you can see for now we only have one replicator field called blocks that we will add new sets into it.

We start by grouping our sets, as you saw on the picture, we have Header Sections, Featured Sections, etc.. and for now they are ordered as 1, 2, 3 etc. But, we will start by writing just the category name in our case it will be like this:

  • Header Section
  • CTA Section
  • Featured Section
  • Logo Cloud
  • Testimonial Section
  • Partner Section
  • Gallery Section

Here we have only 6 categories, and inside them we can have as many variations as we want. Usually you might have 2-3 variations for each block depending on the scale of your website. So how do we target each file in these sets? In our case we decided to go with button group but you are free to use select for a more compact view.

Here is a config for one of our sections, the CTA Section:

  display: "CTA Section"
    - handle: version
          cta_section_1: "Version 1"
          cta_section_2: "Version 2"
          cta_section_3: "Version 3"
        display: "CTA Version"
        default: "cta_section_1"
        type: button_group
        icon: button_group
        instructions: "Select a CTA Style"
        listable: hidden
          - required
    - handle: title
        input_type: text
        antlers: false
        display: Title
        type: text
        icon: text
        listable: hidden
          - required
    - handle: description
        antlers: false
        display: Description
        type: textarea
        icon: textarea
        listable: hidden
    - handle: link
        display: Link
        type: link
        icon: link
        listable: hidden

As you can see for our CTA Section we have a button group for each version, the values of each option represents one file in our template. Basically cta_section_1 should be under partials/sets/cta_section/cta_section_1.antlers.html but we will touch on this a bit later. Note that there is a default value on our button group, this is to mitigate any error when used in a Live Preview window.

Also very important for your button group (or if you prefer select) to have a handle name of version as we will use this in the frontend. Our CTA Section has a title, description and a link field.

You can go into more detail and add more fields for each CTA field and then trigger their visibility by the version value but that is up to you.

Here is how we organize our files in the frontend, under resources/views/ we have a folder for sets. Under sets we have the following structure:

  • cta_section
    • cta_section_1.antlers.html
    • cta_section_2.antlers.html
    • cta_section_3.antlers.html
  • logo_cloud
    • logo_cloud_1.antlers.html
    • logo_cloud_2.antlers.html
    • logo_cloud_3.antlers.html

You can do this for all the block categories that you have and create different versions for each one of them.

Please note that the root folder is the name of the handle, and the file names should be based on the options that you provided under versions in the config above.

To display each set in our frontend, we have to go to resources/views/pages/show.antlers.html and add the following code:

{{ block }}
    {{ partial src="sets/{type}/{version}" }}
{{ /blocks }}

And now in our replicator for each section we only have the name of the category:

This is way cleaner and user-friendly than what we had before.

In our control panel every section is neatly displayed and you can select different versions for each section in a simple way. Here is how our CTA Section looks like with 3 versions:

Check the code and look at a basic example repo here.

If you are interested for a great Statamic Starter Kit to boost your design and development time, check here.

Stay up to date

Be updated with all news, products and tips we share!