What's the difference between a section and a block in Shopify?

A section is a whole horizontal band of a page. A block is one repeating item inside that band. The row of four promises across your homepage is one section; each promise in it is a block. You add and reorder sections in the theme editor sidebar, and you add and reorder blocks underneath whichever section you have selected.

That single distinction explains most of what feels broken about the theme editor. It explains why some sections have an Add block button and most do not, why the button greys out after the fourth item, and why a block you built in one section cannot be dragged into another. We counted all three across our own archive of generated themes, and the numbers are further down.

What is a section in Shopify?

A section is one file in the theme's sections folder that renders one band of a page. Every section file ends with a {% schema %} tag holding JSON that tells the theme editor what the merchant is allowed to change. In our archive of 13 complete generated themes, all 329 section files carry exactly one parseable schema, which is a hard requirement: Shopify errors out if a file has two schema tags or nests one inside another Liquid tag.

Sections are the unit you add, remove and reorder on a page. Their settings apply to the entire band, so they tend to be things like the heading above the row, the background color, the vertical padding, or how many columns the row uses. Across those 329 sections we counted 1,885 settings, a median of 4 per section, of which 1,335 are text fields of some kind.

Thirteen of the 329 have no settings and no blocks at all. Those are the ones where you click the section in the sidebar and the right panel is empty. Nothing is wrong. The theme author built that band to be fixed, and the only way to change it is in the code.

What is a block in Shopify?

A block is one repeating item inside a section. A single FAQ question, one testimonial, one footer column, one slide in a slideshow. The section decides the layout and the blocks fill it, which is why the section's Liquid loops over them with {% for block in section.blocks %} and renders each one according to its type. (How that loop behaves, including what limit, where and hidden blocks do, is tested in our block loop guide.)

Blocks defined inside a section's own schema are called section blocks, and Shopify's documentation sets two rules that catch people out. You can only use section blocks within the section where they are defined, and you cannot nest other blocks inside a section block. So a block is not portable and it is not a container. If you spent ten minutes building a testimonial block with a photo, a quote and a name, that work belongs to that one section forever.

Block settings are smaller than section settings, as you would expect from something that repeats. Across the 125 block types defined in our archive, the median block has 3 settings, with a range from 1 to 16.

Section or block: which one am I looking at?

One reliable tell in the editor: the sidebar label of a block is usually taken from its own content rather than its type. Shopify's editor looks for a setting with the id heading, then title, then text, and uses that value as the label. So a block reading "Free shipping over 50" is showing you its own text, while a section is labelled with the name its author gave it.

Why does this section have no Add block button?

Because most sections do not define blocks, and a section that defines none cannot accept any. In our archive, 113 of 329 section files declare blocks and 216 do not. That is 34.3 percent, so roughly two out of every three sections you click on will offer you settings and nothing else.

This is a deliberate choice by the theme author, not a defect. A hero band with one headline and one button has nothing to repeat, so giving it blocks would only add an empty menu. The practical consequence is that "there is no Add block button" is almost never something you can fix from the theme editor. Either use a different section that does take blocks, or edit the section's schema in the code.

Which sections tend to take blocks is fairly predictable. In our archive the repeat offenders are FAQ accordions (13 of 13 themes), footers (11), galleries (8), heroes with stat or slide items (8), product showcases (8) and testimonial rows (7).

There is a separate version of this problem where the section does take blocks but the one you want is missing, which is usually an app block rather than a theme block. We covered that case in why you can't add your app's block to your theme. If the section itself is missing from the Add section menu, that is a third and different problem, covered in why you can't add a section in the theme editor.

Why did the Add block button stop working after four items?

Because the section hit its max_blocks cap. Shopify allows 50 blocks per section by default, but a theme can lower that number in the schema, and themes lower it constantly. The theme editor does not explain this. The button simply stops responding or disappears.

Of the 113 block accepting sections in our archive, 79 set an explicit cap and 34 leave it at the platform default of 50. Here is the whole distribution of those 79 caps, measured on 18 September 2026.

The median cap is 5, and 34 of the 79 stop at four blocks or fewer. Four is the single most common ceiling, tied with six. If you are trying to put a fifth item in a trust row and the editor will not let you, that is almost certainly why, and it is a one line change in the section file rather than a bug.

Caps are usually there for a layout reason. A four column trust row with five items wraps one lonely item onto a second line, so the author stopped it at four. Raising the cap is easy; making the fifth item look right is the actual work.

What are Shopify's real limits on sections and blocks?

These are platform limits, so they apply no matter which theme you use. Exceeding one produces an error in the theme editor or when the theme is saved, uploaded or synced with the CLI.

Two notes worth keeping. The per section and per template block limits count only blocks a merchant can add, remove or reorder, so statically rendered blocks added with {% content_for %} do not eat into them. And the 25 section ceiling is per template, not per store, so a long homepage does not restrict your product page.

For context on what a normal page actually uses: the homepages in our archive run 9 to 11 sections with a median of 10, and carry a median of 22 blocks. So a typical homepage sits at 40 percent of the section limit, and about two thirds of everything you would edit on it is a block rather than a section.

Section blocks, theme blocks and app blocks

There are three kinds of block and the theme editor shows them in the same list, which is where a lot of the confusion starts.

Theme blocks are the newer model and the more flexible one, because the same block file can be offered by many sections and can contain other blocks. Section blocks are the older model and are still extremely common, which is why "I cannot move this block" is a normal answer rather than a workaround failure.

App blocks are the one to check if an app's instructions tell you to add its widget and the option is not there. Every one of the 113 block accepting sections in our archive uses named section block types rather than @app, which is a real limitation of that generation of our themes and exactly the situation the app block page above describes.

Which one do I edit to change this?

If I change a section on one page, does it change on every page?

Only if that section lives in the header, the footer or the theme's layout file. A section you added to a page in the theme editor is its own copy with its own settings, so editing it changes that page and nothing else, even when the same kind of section sits on ten other pages. Sections in the header and footer areas belong to a section group, and every page that shows the group shows the same copy, so a change there lands everywhere at once.

There is a third, older kind called a static section: a section written straight into the theme's layout file with the {% section %} tag. It has a single set of settings for the whole theme, so it also changes on every page, and because it is part of the code you cannot remove or reorder it from the editor.

We checked all three on our development store on 26 October 2026, using an unpublished test theme pushed with Shopify CLI 3.93.1. One section file was added twice to the homepage template and once to the search template, with different text in each copy. The homepage printed "home first" and "home second", and the search page printed "search only". A header group section and a static section both printed the same value on both pages. Then we added the same file to the search template as an ordinary section with its own text. The page showed the static copy's text and the new copy's text side by side: one section file, two separate sets of settings.

The practical rule: if a change you made shows up somewhere you did not expect, the section is in a group or the layout. If a change you made on one page is missing from another, that other page has its own copy, and it needs the same edit.

Why did a section disappear from one page with no error?

Most likely the section file now restricts which pages may use it. A section schema can carry enabled_on or disabled_on, which list the templates and groups it is allowed on. When a theme update or a code edit adds that restriction, copies already sitting on an excluded page stop rendering, and nothing in the storefront says why.

In our test, adding "enabled_on": {"templates": ["index"]} to the section already on the search page was accepted without complaint, and the copy on the search page was gone within about ten seconds while the homepage copies stayed. Its settings were not deleted. Taking the restriction back out brought it back with its original text on the next request. The error only appears later, when the search template itself is uploaded again: Shopify refuses it with Section 'a' is not supported on search templates. The 'a' is the section's id inside the template file, so in a real theme expect a long generated id rather than a name you recognise.

The other schema restriction behaves differently. Setting "limit": 1, which caps how many copies of a section one page can hold, hid nothing: the homepage kept rendering both copies for the 30 seconds we watched. Again the template was refused on its next upload, this time naming the type instead of the id.

In each refused case the previous version of the template stayed live, so the store did not break, but any other change in that same file was not saved either. Blocks have a matching trap: removing a block type from a section's schema hides those blocks the same way. If a whole section is missing from the Add section list rather than from one page, the cause is usually different and is covered in why you can't add a section in the theme editor.

How we measured this

Every count on this page comes from parsing the {% schema %} JSON out of every section file in 13 complete generated Shopify themes in our own build archive, run on 18 September 2026. That is 329 section files, all 329 with a valid schema and zero parse failures. Of those, 113 declare blocks, 79 declare an explicit max_blocks, and 125 distinct block types are defined in total. Homepage counts come from reading templates/index.json in each theme and counting entries in order and blocks.

The one page or every page tests and the disappearing section tests were run on 26 October 2026 against an unpublished probe theme on our own development store, pushed with Shopify CLI 3.93.1 and read back through the theme preview. Each restriction was added, checked over 30 seconds, and removed again, and the hiding result was seen on two separate runs. The probe theme was deleted afterwards.

The platform limits in the table above are Shopify's published theme limits, not our measurements.

If you would rather look at a finished theme than a schema, every theme in our free theme gallery has a live preview you can open and scroll, with the sections and blocks already filled in.