Custom section not showing in the Shopify theme editor? Here's the fix

You have written or downloaded a custom section, added it to your theme, and gone to the theme editor to place it. It isn't in the list. Shopify rarely explains why: the editor simply doesn't offer sections it can't use. The good news is that the causes are few and easy to check. Go through the checklist below in order; the early steps cover the most common problems.

The checklist

1. Check the schema has presets

   The theme editor only lists sections that have a presets array in their {% schema %}. Without it, the section is valid and can still be used in a template file, but it never appears under "Add section". Add at least one preset with a name: "presets": [{ "name": "Promo banner" }]. That name is what the merchant sees in the list.

2. Validate the schema JSON

   The content between {% schema %} and {% endschema %} must be valid JSON. The usual culprits are a trailing comma after the last item in an array or object, // comments, single quotes instead of double quotes, and Liquid tags inside the schema (which aren't allowed). Shopify's code editor normally refuses to save an invalid schema and shows an error, but files pushed with the CLI or uploaded in a theme zip can fail more quietly. Paste the schema into the section schema generator or run shopify theme check to find the line.

3. Confirm the file is in the sections folder

   The file must live in sections/ and end in .liquid, for example sections/promo-banner.liquid. A file in snippets/ is a snippet, not a section, and a name like promo-banner.liquid.txt or promo-banner.html is ignored. Also check there is exactly one {% schema %} tag in the file.

4. Check enabled_on and disabled_on

   These schema keys limit where a section can be added. "enabled_on": { "templates": ["product"] } means the section only shows when you are editing a product template; "disabled_on": { "groups": ["header", "footer"] } keeps it out of the header and footer. If you are on the home page and the section is enabled only for products, it won't be listed. Older sections may use a top-level templates array for the same purpose; it is the legacy form, and you shouldn't combine it with enabled_on or disabled_on.

5. Add it in the right place: section groups vs templates

   Online Store 2.0 themes have two areas. The header and footer are section groups, shared across every page; everything in between belongs to the template you are editing. Click "Add section" in the area you want. A section restricted to groups won't appear in a template's list, and the reverse is also true. A section rendered with the {% section %} tag in a layout file is static: it shows in the editor only where it's rendered and can't be added from the list.

6. Check you haven't hit a limit

   Shopify currently allows up to 25 sections in a JSON template and up to 50 blocks per section. At the section limit the editor stops offering "Add section" for that template. Remove an unused section or move some content into blocks. A preset that asks for more blocks than its own limit or max_blocks allows is invalid.

7. Keep the section name short

   The schema name and preset names should be short. Shopify caps the schema name at 25 characters, and a longer one is rejected as an invalid schema. "Testimonials with star ratings and photos" won't work; "Testimonials" will.

8. Make sure you are editing the right theme

   Under Online Store > Themes, the code editor and the theme editor each belong to one theme. It is very easy to upload the file to a draft copy and then click Customize on the live theme, or the reverse. Open the code editor from the same theme's menu and confirm the file is there.

9. Hard-refresh the theme editor

   The editor caches the list of sections. After adding or changing a file, reload the editor with a hard refresh (Cmd+Shift+R on Mac, Ctrl+Shift+R on Windows), or close and reopen it. If you are working through the Shopify CLI, make sure the push or shopify theme dev sync actually finished without errors.

Symptom, cause and fix

A minimal schema that will appear

If you're unsure what's wrong, strip the schema back to something known to work, confirm the section appears, then add your settings back a few at a time. This is the smallest schema that shows up in the list on any template:

<div class="test-section">
  <h2>{{ section.settings.heading | escape }}</h2>
</div>

{% schema %}
{
  "name": "Test section",
  "settings": [
    { "type": "text", "id": "heading", "label": "Heading", "default": "It works" }
  ],
  "presets": [
    { "name": "Test section" }
  ]
}
{% endschema %}

If even this doesn't appear, the problem isn't your code: it's the theme you are editing, a template that is full, or a cached editor.

If your theme is not Online Store 2.0

Older, "vintage" themes use .liquid templates rather than JSON templates, and only the home page lets you add sections freely. On other pages of a vintage theme there is no "Add section" button at all; a section has to be included in the template code. If your theme was installed years ago and has never been replaced, check the templates folder: files ending in .json mean Online Store 2.0, files ending in .liquid mean vintage.

Avoiding the problem next time

Most of these issues are schema mistakes that are easy to make by hand and easy to catch with a check. Validate every schema before uploading, keep names short, add presets from the start, and only use enabled_on when you really mean to restrict a section. The steps for installing a section cleanly are in how to add a custom section to Shopify, and the details of blocks and presets are in how to add blocks to a Shopify section.

Sections written by Klorr come with valid schema, presets and default blocks already in place, so they appear in "Add section" as soon as they are in the sections folder. If you would rather start from a finished section, the Klorr marketplace has ready-made ones to install.