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.

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?

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