Theme frames

A theme frame is a configuration of sections to display around the content of a page. Instead of hard-coding this content in theme layouts, such as layout/theme.liquid, themes may opt into using the theme frame feature by implementing a config/frames.json file. Merchants can customize theme frames in the Online Store editor.

Theme frames only use frame sections. These are the top-level sections displayed at the top and bottom of the page, like header and footer. They aren’t standardized by Shopify.

Rules for theme frames

  • config/frames.json must contain at least one theme frame.
  • Only frame sections can be used in theme frames.
  • At least one theme frame must have the ID default. This is the default frame used by all pages.
  • Theme frames can be used by pages using both the sections or template architecture. In both cases the content of the page, sections or theme template, is injected between the top and bottom frame sections.
  • The layout property defines which theme layout to use when rendering the page. If a theme template uses the {% layout %} tag, its value takes precedence over the layout defined in the theme frame.
  • Like in config/settings_data.json, the value of resource-type settings must be resource handles. This is to facilitate copying themes across stores.
  • If a theme implements theme frames, it may not use the {% section %} tag in its layout files.

The config/frames.json theme file

The config/frames.json theme file stores data for one or more theme frames.


  <ThemeFrameId>: <ThemeFrame>


  "name": <String>,
  "wrapper": <ThemeFrameWrapper>,
  "layout": <ThemeLayoutName>,
  "top": [<ThemeFrameSectionData>],
  "bottom": [<ThemeFrameSectionData>]


  "id": <SectionId>,
  "file": <String>,
  "settings": {
    <SettingId>: <SettingValue>
  "blocks": [<BlockData>]


A config/frames.json containing a default theme frame configuration:

  "default": {
    "name": "Default",
    "top": [
        "id": "header",
        "file": "header"
    "bottom": [
        "id": "footer",
        "file": "footer"

The wrapper property

The wrapper property makes it possible to insert HTML tags around the inner sections of theme frames. This allows developers to use containers and other tags around the middle portion of pages.

The wrapper property is defined inside the theme frame configuration. The element tree and element attributes are specified in a syntax similar to CSS selectors.


The following theme frame:

    "default": {
      "name": "Default",
      "wrapper": "div.container[data-attribute=\"value\"] main#main",
      "top": [ ... ],
      "bottom": [ ... ]

renders the following markup:

[top sections]

<div class="container" data-attribute="value">
  <main id="main">
    [inner sections]

[bottom sections]

Supported tags that can be added to the wrapper property:

  • <div>
  • <main>
  • <section>

Theme frame assignment

Pages can be assigned a specific theme frame using the theme_frame_id attribute returned by the API. When theme_frame_id is blank, the page is rendered using the frame whose ID matches the page type. For example, product for product pages.

If there is no corresponding theme frame for the page type, the page will fall back to using the default theme frame.

Password and gift card pages are commonly set up to have their own frame as these pages rarely have typical headers or footers.

Ready to start selling with Shopify?

Try it free