12/30/21, 1:35 AM How to Create Your First Shopify Theme Section — Shopify Theme Development (2021)

Build an app to power Shopify’s 1,700,000+

merchants
Join the Shopify Partner Program for free and access educational resources, developer
preview environments, and recurring revenue share opportunities.

Join now

Show

ArticlesGuidesWebinarsEventsToolsWhat’s new at ShopifyDeveloper Interview Series

Home
Web Design and Development Blog
How to Create Your First Shopify Theme Section

How to Create Your First Shopify Theme Section

by Liam Griffin
Shopify Theme Development
Aug 3, 2021
9 minute read
Leave a comment

https://www.shopify.com/partners/blog/how-to-create-your-first-shopify-theme-section 1/20
12/30/21, 1:35 AM How to Create Your First Shopify Theme Section — Shopify Theme Development (2021)

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. We originally published this article in
2018 but have updated it to the new standards of Online Store 2.0 so
you have the most up-to-date information. 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? 

https://www.shopify.com/partners/blog/how-to-create-your-first-shopify-theme-section 2/20
12/30/21, 1:35 AM How to Create Your First Shopify Theme Section — Shopify Theme Development (2021)

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. 

https://www.shopify.com/partners/blog/how-to-create-your-first-shopify-theme-section 3/20
12/30/21, 1:35 AM How to Create Your First Shopify Theme Section — Shopify Theme Development (2021)

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

would be:

1 {
2 "name": "Product",
3 "sections": {
4 "main": {
5 "type": "main-product"
6 }
7 },
8 "order": [
9 "main"
10 ]
11 }

product.json
hosted with ❤ by GitHub view raw

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.

https://www.shopify.com/partners/blog/how-to-create-your-first-shopify-theme-section 4/20
12/30/21, 1:35 AM How to Create Your First Shopify Theme Section — Shopify Theme Development (2021)

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
preset 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. 

https://www.shopify.com/partners/blog/how-to-create-your-first-shopify-theme-section 5/20
12/30/21, 1:35 AM How to Create Your First Shopify Theme Section — Shopify Theme Development (2021)

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
preset within its schema. Once these presets
preset are
added, the section will be an available option when the merchant clicks Add
section in the theme editor.

https://www.shopify.com/partners/blog/how-to-create-your-first-shopify-theme-section 6/20
12/30/21, 1:35 AM How to Create Your First Shopify Theme Section — Shopify Theme Development (2021)

https://www.shopify.com/partners/blog/how-to-create-your-first-shopify-theme-section 7/20
12/30/21, 1:35 AM How to Create Your First Shopify Theme Section — Shopify Theme Development (2021)

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 
https://www.shopify.com/partners/blog/how-to-create-your-first-shopify-theme-section 8/20
12/30/21, 1:35 AM How to Create Your First Shopify Theme Section — Shopify Theme Development (2021)

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:

1 <div class="custom-text-section">
2 <h2> {{ section.settings.custom_text_title }} </h2>
3 <div>{{ section.settings.custom_text_body }}</div>
4 </div>
5

6 {% schema %}
7 {
8 "name": "Text Box",
9 "settings": [
10 {
11 "id": "custom_text_title",
12 "type": "text",
13 "label": "Text box heading",
14 "default": "Title"
15 },
16 {
17 "id": "custom_text_body",
18 "type": "richtext",
19 "label": "Add custom text below",
20 "default": "<p>Add your text here</p>"
21 }
22 ]
23 }
24 {% endschema %}

custom-text.liquid
hosted with ❤ by GitHub view raw

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. 

https://www.shopify.com/partners/blog/how-to-create-your-first-shopify-theme-section 9/20
12/30/21, 1:35 AM How to Create Your First Shopify Theme Section — Shopify Theme Development (2021)

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
preset
in the section. 

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

"presets":
preset [

"name": "custom-text",

"category": "Custom"

https://www.shopify.com/partners/blog/how-to-create-your-first-shopify-theme-section 10/20
12/30/21, 1:35 AM How to Create Your First Shopify Theme Section — Shopify Theme Development (2021)

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

1 <div class="custom-text-section">
2 <h2> {{ section.settings.custom_text_title }} </h2>
3 <div>{{ section.settings.custom_text_body }}</div>
4 </div>
5

6 {% schema %}
7 {
8 "name": "Text Box",
9 "settings": [
10 {
11 "id": "custom_text_title",
12 "type": "text",
13 "label": "Text box heading",
14 "default": "Title"
15 },
16 {
17 "id": "custom_text_body",
18 "type": "richtext",
19 "label": "Add custom text below",
20 "default": "<p>Add your text here</p>"
21 }
22 ],
23 "presets":
preset [
24 {
25 "name": "custom-text",
26 "category": "Custom"
27 }
28 ]
29 }
30 {% endschema %}

custom-text.liquid
hosted with ❤ by GitHub view raw

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. 
https://www.shopify.com/partners/blog/how-to-create-your-first-shopify-theme-section 11/20
12/30/21, 1:35 AM How to Create Your First Shopify Theme Section — Shopify Theme Development (2021)

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

https://www.shopify.com/partners/blog/how-to-create-your-first-shopify-theme-section 12/20
12/30/21, 1:35 AM How to Create Your First Shopify Theme Section — Shopify Theme Development (2021)

recommendations section on the page by adding a new object below the

"main" section:

1 {
2 "name": "Product",
3 "sections": {
4 "main": {
5 "type": "product-template"
6 },
7 "recommendations": {
8 "type": "product-recommendations"
9 }
10 },
11 "order": [
12 "main",
13 "recommendations"
14 ]
15 }

product.json
hosted with ❤ by GitHub view raw

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

preset 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
preset are present within the schema settings.
https://www.shopify.com/partners/blog/how-to-create-your-first-shopify-theme-section 13/20
12/30/21, 1:35 AM How to Create Your First Shopify Theme Section — Shopify Theme Development (2021)

"presets":
preset [

"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.

https://www.shopify.com/partners/blog/how-to-create-your-first-shopify-theme-section 14/20
12/30/21, 1:35 AM How to Create Your First Shopify Theme Section — Shopify Theme Development (2021)

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

https://www.shopify.com/partners/blog/how-to-create-your-first-shopify-theme-section 15/20