Unlocking Dynamic Collection Pages: A Guide to Custom Sections & Metafields on Shopify

Hey there, fellow store owners!

I recently dove into a really insightful discussion on the Shopify community forums that I just had to share with you all. It revolved around a common challenge: how to add a custom section, especially one that uses metafields, to your Shopify collection pages. Our friend, Pickleball2, was trying to get a dynamic hero carousel or banner working on their www.pickleballbella.com store, running on Dawn 2.0, and hit a few snags. And honestly, it’s a hurdle many of us face when we start digging into theme customization.

The core of the issue, as often happens, came down to understanding how Shopify's Online Store 2.0 themes (like Dawn) structure their files and how Liquid code interacts with JSON templates. Let's break down what we learned and how you can apply it to supercharge your own collection pages!

Understanding Shopify's Theme Architecture: JSON, Sections, and Snippets

One of the biggest takeaways from the thread, brilliantly clarified by community member Maximus3, is the distinct roles of the different file types in your theme. This is crucial for avoiding those head-scratching "file save errors" Pickleball2 initially encountered.

• JSON Templates (e.g., templates/collection.json): These files are the blueprints for your pages. They tell Shopify which sections to load and in what order. Think of them as a table of contents. Crucially, JSON templates contain NO Liquid code. They only list section IDs and their settings.
  
  
  
• Liquid Sections (e.g., sections/my-custom-section.liquid): These are the actual building blocks. They contain all the HTML, CSS, JavaScript, and most importantly, the Liquid code that defines what your section looks like and how it behaves. If you want to check for metafields or render different content based on conditions, this is where that logic lives! Sections also contain a {% schema %} block at the bottom, which defines the settings you can control in the Theme Customizer.
  
  
  
• Liquid Snippets (e.g., snippets/product-card.liquid): These are smaller, reusable chunks of Liquid code, often called by sections using the {% render 'snippet-name' %} tag. They don't have their own schema and aren't directly added to JSON templates.
  
  
  

Pickleball2's initial "file save error" and the subsequent "Could not find asset snippets/collection-header.liquid" error, as Laza_Binaery and ajaycodewiz pointed out, stemmed from trying to put Liquid rendering logic directly into the collection.json file or referencing snippets that didn't exist. It's a classic mix-up, and trust me, we've all been there!

Adding Your Custom Section: Two Main Paths

Now that we understand the structure, let's look at the two primary ways to get that custom section onto your collection page. Remember sadik_ShopiDevs' advice: always duplicate your theme before making direct code edits!

Option 1: The Theme Customizer Way (Easiest for Many)

This is often the simplest route, especially if your custom section doesn't require super complex conditional logic tied to specific template files. If your section is designed to be added anywhere, just make sure its schema supports the collection template:

1. Enable Collection Template Support in Your Section File:

   Open your custom section file (e.g., sections/pbb-collection-hero-carousel.liquid). Inside its {% schema %} block, add "enabled_on":

   {% raw %}{
     "name": "Collection custom section",
     "settings": [],
     "enabled_on": {
       "templates": ["collection"]
     },
     "presets": [
       {
         "name": "Collection custom section"
       }
     ]
   }{% endraw %}
   

2. Add via Theme Customizer:

   Go to Online Store → Themes → Customize. Navigate to a collection page (e.g., Collections → Default collection). Click Add section in the left sidebar, select your custom section, and save. You can then drag and drop it into place!

   
   
   
   

For simple Liquid snippets, Maximus3 also suggested using the "Custom Liquid" section directly in the theme editor. This is great for quick, isolated code blocks without creating a whole new section file.

Option 2: Manual JSON Template Editing (for Advanced Control & Conditional Metafield Logic)

This is the path Pickleball2 was heading down and is ideal when you want to define a specific layout for a collection page or if you need to integrate conditional logic based on metafields directly into a custom template. This is where ajaycodewiz's detailed explanation really shines.

1. Create or Modify Your Custom Section File (e.g., sections/pbb-collection-hero-carousel.liquid)

   This file holds the actual content and logic. If you want it to only show when a metafield is populated, add that conditional Liquid code here. For Pickleball2's case, it looked something like this:

   {% raw %}{% if collection.metafields.custom.hero_images.value != blank %}
   
     {% render 'collection-hero-carousel' %}
   
   {% elsif collection.image %}
   
     {% render 'collection-featured-image' %}
   
   {% else %}
   
     {% render 'collection-header' %}
   
   {% endif %}
   
   {% schema %}
   {
     "name": "Collection Hero",
     "settings": [],
     "presets": [
       {
         "name": "Collection Hero"
       }
     ]
   }{% endraw %}
   

   Important: Laza_Binaery rightly pointed out the Liquid error: Could not find asset snippets/collection-header.liquid. This means any snippets you {% render %} (like collection-hero-carousel or collection-header) must exist in your snippets/ folder. If they don't, you'll get errors. Double-check those filenames!

2. Edit Your Collection JSON Template

   You can either modify your existing templates/collection.json or, better yet, create a new custom collection template (e.g., templates/collection.pbb-custom.json) if you want this layout for only specific collections. This is where you tell Shopify to include your custom section.

   Here's how you add your section reference:

   {% raw %}{
     "sections": {
       "carousel": {
         "type": "pbb-collection-hero-carousel",
         "settings": { "color_scheme": "scheme-053ea910-6eb4-4198-8577-e17b5ab7c241" }
       },
       "banner": { "type": "main-collection-banner", "settings": { "...": "..." } },
       "product-grid": { "type": "main-collection-product-grid", "settings": { "...": "..." } }
     },
     "order": [
       "carousel",
       "banner",
       "product-grid"
     ]
   }{% endraw %}
   

   Notice a few things:

   • Under "sections", you create a unique ID (like "carousel") for your section instance.
   • The "type" property must exactly match your section filename without the .liquid extension (e.g., pbb-collection-hero-carousel.liquid becomes "pbb-collection-hero-carousel").
   • Under "order", you list the IDs of all sections in the exact sequence you want them to appear. Pickleball2's error for "file save error" was likely a missing comma between "carousel" and "banner" in the "order" array. JSON is very strict about syntax!
   
   
   
   

3. Apply the Custom Template to Your Collections

   If you created a new template (e.g., collection.pbb-custom.json), you need to tell your collections to use it. Go to Online Store → Collections → (your specific collection). On the right sidebar, under "Theme template," select your new custom template from the dropdown.

   
   
   
   

4. Set Up Your Collection Metafields

   Finally, the "metafield" part! Go to Settings → Custom data → Collections. Add a metafield definition that matches the namespace and key you used in your section's Liquid code (e.g., custom.hero_images). Then, for each collection where you want the section to appear, populate that metafield with your desired content. If the metafield is left blank, your Liquid condition ({% if collection.metafields.custom.hero_images.value != blank %}) will ensure the section doesn't render, keeping your page clean.

   
   
   
   

This approach gives you incredible flexibility to create unique, dynamic collection pages that adapt based on the data you provide. It’s a powerful feature for any growing Shopify store looking to stand out.

So, whether you're just starting with Shopify or you're a seasoned merchant, understanding this distinction between JSON templates, Liquid sections, and snippets is key to unlocking the full potential of your store's design. Don't be afraid to experiment, and always keep a duplicate theme handy for testing! Happy customizing!