Shopify Partners

How To Create Your First Shopify Theme Section

how-to-create-your-first-shopify-theme-section

Announcing Online Store 2.0

Online Store 2.0 is an end-to-end overhaul of how themes are built at Shopify, launched June 2021. While the information in the following article is still correct, it doesn’t account for Online Store 2.0 best practices, and may not include references to recent features or functionality. To learn more about how to build with Online Store 2.0, visit our updated documentation.

Visit docs


Giving your clients creative control is key, especially when they want the ability to customize their storefront. Shopify’s sections feature is a powerful tool for personalizing Shopify themes, so using them efficiently and following best practices will unlock a range of options for your clients.

If you’re building a Shopify theme from scratch or tweaking a theme for a client, you’ll need to create a few different types of sections, which will vary depending on context. Additionally, customers expect a user-friendly and intuitive experience, meaning the right section, in the right place can have a huge impact on conversion.

In this article, we’ll cover how to get started with creating different types of theme sections, and the rules for using them, so that you can help empower your clients to customize their store. We’ll also explore some examples of specific sections from our source-available Dawn theme, to demonstrate exactly how you can use them in real world scenarios. 

What are theme sections? 

At a high level, sections are modular components of a Shopify theme that merchants can customize. Sections contain content and settings for specific areas of a Shopify store, such as the basic elements of a product page, or a slideshow component. 

Within these sections, developers have access to a range of different setting types, from text inputs and image pickers, to custom HTML and menus, that merchants can customize from the theme editor and populate with their content. 

Sections are contained within the /sections directory of a theme, and can be statically included in a theme’s layout files (like the header and footer), or they can be dynamically added to any template from the Theme Editor. To get a sense of the various components which can be represented as sections, you can explore the /sections directory of the Dawn theme. 

With the launch of Online Store 2.0, sections can now be used as the primary way to organize all the different aspects of your theme, from whole pages, to individual elements. As we’ll cover in this article, the ability to add sections to any JSON templates will allow you to easily arrange different pages, which can be further enhanced when merchants customize their theme. 

Templates and sections

One of the prerequisites for learning how sections work on Shopify themes is understanding Shopify’s theme templates system. With Online Store 2.0, each page type can be represented as a .json file within the /templates directory of a theme. Developers can structure each page type by defining which sections will appear by default in these JSON template files

These JSON templates don’t include any markup or Liquid objects for displaying store content, they are simply data files that indicate which sections will appear by default on a page, and in what order. 

A basic example of what a product.json template file could look like would be:

In this case, a product page would render with a section called main-product.liquid, and it would be the only section appearing by default. When a merchant customizes this page, and adds more sections to the page, the product.json template file would be updated with this information. We’ll be exploring this process more in this article when we look at how sections are included in templates. 

Basics of sections 

When developing your theme using sections and JSON templates, you can consider building section files in two distinct categories: “main” page sections, and individual modular components. 

Main page sections

Within a main page section, you should include all the default content for that page. For example, in the main section for a product page, you would include the important elements to display a product and its associated properties such as product title, description, media, price, and the add-to-cart form.

You can access Liquid variables, or objects, within a section, based on which page template a section is included in. This means that a section that will be rendered within a product.json template will be able to access any attributes of the product Liquid object, representing the product whose page is being rendered. 

Similarly, a section that is included in a collection.json file will be able to access all attributes of the collection Liquid object. All sections, regardless of where they appear, can access any of the Liquid global objects

In addition to the markup and page-specific Liquid objects you’ll be adding to a main page section, you can also create settings within {% schema %} tags. These settings can reference elements in the section, and can be configurable by merchants in the theme editor.

Since a main page section includes markup specific to one type of page, you’ll only want to include it within its associated template. To prevent a main page section from being added to other page types from the theme editor, it should not contain presets within its section schema. 

To view an example of a main page section, you can explore the main-product.liquid file in the /sections directory of Dawn, or any of the sections that are prefixed with main in the title. As a general rule, you should also name your main page sections with main in the title to help you distinguish between different section types.

Modular sections

Modular sections are sections that can be reused in different areas of an online store, and supplement the main elements of a page. Examples of these types of sections include featured collections, slideshows, and newsletter signup forms. 

These sections would generally be added to pages by merchants using the theme editor, rather than the sections being added by default to a page template. In order for a section to be added to a page via the editor, the section must contain presets within its schema. Once these presets are added, the section will be an available option when the merchant clicks Add section in the theme editor.

Shopify theme section: Gif of the theme editor options, cursor selecting

In contrast to “main” page sections, modular sections typically contain content and markup that can be reused across different page types, and in different contexts, on a Shopify store. Developers should therefore avoid relying on page-specific Liquid objects within these sections. 

It’s possible, however, to restrict a section to only be available on specific page types by using the templates attribute within the section schema. For example, if you wanted to limit a section to only product and collection pages, you would include this line within the section’s schema tags:

"templates": ["product", "collection"] 

The templates attribute accepts a list of strings that represent the page type.

Based on what functionality you want to include in your theme, or what specific requirements your client has, you’ll likely be creating a range of different sections that enable unique features. To view examples of modular sections, you can explore the newsletter section or rich-text section used in Dawn. 

Section settings 

We’ve looked briefly at how a section file’s settings can be used to create customization options that merchants can access, but let’s dive into these a little deeper, to see how they’re constructed. 

As we’ve seen, settings are included within section files, inside {% schema %} tags, which denote that these are settings that should render on the UI of the theme editor. A very simple example of this could be seen with a custom text section that could look something like:

In this example we have two HTML elements: a heading element and a paragraph element. Each of these elements contains dynamic content that we’ve created with the section.settings Liquid object. This section object allows us to retrieve setting values by referencing the setting’s unique ID. 

Below the HTML and Liquid markup we have our section settings, contained in our {% schema %} tags. Each setting is represented by an object, where we can define the setting id, its type and how it will appear on the editor. To access a section’s setting in Liquid, append its id to the section.settings liquid object. We also define the type of setting it is and how it will appear on the theme editor. 

Within the settings of our schema tags:

  • id refers to the Liquid variable being defined 
  • type defines the kind of output we are creating
  • label provides context displayed on the theme editor
  • default assigns a default value

In this example, I’ve created a text box for our heading and a richtext box for our body, but you could add a wide range of output types, depending on your client requirements. Other valid input types include image_picker, radio, video_url, and font_picker.

This example is now a valid section, however we’re missing one key aspect: determining where exactly the section will appear on the theme. We’ll explore a few different approaches for including sections later, but for now we’ll allow the section to be added via the theme editor to any page by creating presets in the section. 

Presets are default configurations of sections and are added within a section’s {% schema %} tags. In our simple example, the presets could look like:

"presets": [

{

"name": "custom-text",

"category": "Custom"

}

]

Once added to our example, the custom text-box section would look like:

Now, if we navigate to the theme editor, and select Add section on any page, this section will appear as an available option. The section settings we’ve created will appear on the right sidebar with the labels and default text we’ve added, and we can populate the input text settings, which will be displayed on our section. 

Shopify theme section: Gif of cursor playing around with section settings and the different variables you can adjust

This is a simple example that shows the relationship between section settings and variables that you can create within sections, as well as how these render on the theme editor. For a more advanced model you can explore the rich text section of the Dawn theme

Including sections on pages 

As we’ve already touched upon, there are a number of methods for including sections on pages of a theme. Let’s explore each of these approaches individually, and unpack some of the rules that apply to them.

1. Including sections in JSON templates

When we looked at main page sections, we saw that JSON template files accept a "main" property, which becomes the default section for that page type, and should include all the important content elements for that page. 

In addition to a "main" section, it’s also possible to include other sections in a JSON template that will appear by default on that page type. If we use a product JSON template as an example, we could include a product recommendations section on the page by adding a new object below the "main" section:

In this case we’re assigning a name to the section, recommendations, and the type property is used to identify which file in the /sections directory we want to include. 

Since this JSON template is referencing more than one section, we need to define how the sections appear sequentially, within the order object. Every section included in a JSON template will need to be assigned a default order, however merchants can still rearrange the sections on the theme editor. 

Sections without presets that are added to JSON templates cannot be removed in the theme editor, but they can be hidden if a merchant doesn’t require them. For a real-life example of how sections can be arranged in a JSON template, you can explore the Dawn product template

2. Including sections as options on all pages

As we saw with our custom text, it’s possible to make a section available on all pages of a theme when presets are present within the schema settings.

"presets": [

{

"name": "custom-text",

"category": "Custom"

}

]

When included using this approach, these sections can be added, repositioned, and deleted from the theme editor. These sections can also be limited to specific pages with the templates property

This drag and drop functionality means that when you build custom dynamic sections, a wide range of options for personalizing stores will be unlocked. You can create movable sections for video, products, or image galleries. A good example of a section using this method would be Dawn’s newsletter section

3. Using {% section %} tags to add static sections

The Liquid section tag allows you to render a section from the /sections directory in a Liquid layout or template file. This tag could appear as:

{% section 'header' %} 

Sections added using this section tag cannot be removed, repositioned, or hidden in the theme editor. The position of this section on the page is locked, based on where it has been added within a layout file or template.

This approach is most commonly used for content and components that should always be visible such as headers, footers and announcement bars. To see an example of this on Dawn, you can check out the theme.liquid file where the static announcement bar, header section and footer sections are added with the section tag. 

Empowering creativity

Now that you’ve seen how to create and add sections to your themes, you can build endless options for your clients’ stores. 

Working with JSON templates unlocks the power of sections for all pages of a theme, which will allow merchants to build their store exactly how they would like—with some direction from you.

Grow your business with the Shopify Partner Program

Whether you offer web design and development services or want to build apps for the Shopify App Store, the Shopify Partner Program will set you up for success. Join for free and access revenue share opportunities, developer preview environments, and educational resources.

Sign up

This article originally appeared on the Shopify Web Design and Development blog and is made available here to educate and cast a wider net of discovery.
I'm also on