> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Shopify/horizon/llms.txt
> Use this file to discover all available pages before exploring further.

# Theme Structure

> Detailed breakdown of Horizon's directory structure, sections, blocks, snippets, templates, and assets

## Overview

Horizon follows Shopify's theme architecture with enhanced organization and modern patterns. Understanding this structure is essential for effective theme development.

```
source/
├── assets/          # 100+ CSS, JS, and static files
├── blocks/          # 94 theme blocks
├── config/          # settings_schema.json and settings_data.json
├── layout/          # theme.liquid and password.liquid
├── locales/         # Translation files (en.default.json, etc.)
├── sections/        # 41 section files (.liquid and .json)
├── snippets/        # 93 reusable Liquid snippets
└── templates/       # 14 JSON template files
```

## Sections

Sections are the primary building blocks of Shopify pages. Horizon includes 41 sections organized by purpose.

### Universal Sections

#### `_blocks.liquid` - The Foundation

The `_blocks.liquid` section is Horizon's most flexible container:

```liquid sections/_blocks.liquid theme={null}
{% capture children %}
  {% content_for 'blocks' %}
{% endcapture %}

{% render 'section', section: section, children: children %}

{% schema %}
{
  "name": "t:names.section",
  "class": "section-wrapper",
  "blocks": [
    { "type": "@theme" },    // Accept any theme block
    { "type": "@app" },      // Accept app blocks
    { "type": "_divider" }   // Built-in divider
  ],
  "settings": [
    {
      "type": "select",
      "id": "content_direction",
      "options": [
        { "value": "column", "label": "t:options.vertical" },
        { "value": "row", "label": "t:options.horizontal" }
      ]
    },
    {
      "type": "select",
      "id": "section_width",
      "options": [
        { "value": "page-width", "label": "t:options.page" },
        { "value": "full-width", "label": "t:options.full" }
      ]
    },
    {
      "type": "select",
      "id": "section_height",
      "options": [
        { "value": "", "label": "t:options.auto" },
        { "value": "small", "label": "t:options.small" },
        { "value": "medium", "label": "t:options.medium" },
        { "value": "large", "label": "t:options.large" },
        { "value": "full-screen", "label": "t:options.full_screen" }
      ]
    }
  ]
}
{% endschema %}
```

<Note>
  The `{ "type": "@theme" }` block type allows **any** theme block to be added, making this section universally flexible.
</Note>

### Layout Sections

<Accordion title="Hero Section (hero.liquid)">
  The hero section supports dual media (images/videos), custom layouts, and flexible content positioning:

  ```liquid theme={null}
  {% liquid
    assign media_count = 0
    assign media_1 = 'none'
    assign media_2 = 'none'
    
    if section.settings.image_1 != blank and section.settings.media_type_1 == 'image'
      assign media_1 = 'image'
      assign media_count = media_count | plus: 1
    endif
    
    if section.settings.video_1 != blank and section.settings.media_type_1 == 'video'
      assign media_1 = 'video'
      assign media_count = media_count | plus: 1
    endif
  %}
  ```

  **Key Features:**

  * Dual media slots (desktop + mobile)
  * Blurred reflection effects
  * Custom height options
  * Background overlays with gradients
</Accordion>

<Accordion title="Carousel Section (carousel.liquid)">
  ```liquid theme={null}
  <div class="section section--{{ section.settings.section_width }}">
    {% content_for 'block', type: 'group', id: 'static-header' %}
    {% content_for 'block', type: '_carousel-content', id: 'static-carousel-content' %}
  </div>

  {% schema %}
  {
    "settings": [
      {
        "type": "range",
        "id": "columns",
        "min": 1,
        "max": 8,
        "default": 4
      },
      {
        "type": "select",
        "id": "mobile_columns",
        "options": [
          { "value": "1", "label": "t:options.one_number" },
          { "value": "2", "label": "t:options.two_number" }
        ]
      }
    ]
  }
  {% endschema %}
  ```
</Accordion>

<Accordion title="Collection List (collection-list.liquid)">
  Features the advanced **bento grid** layout system for visually dynamic collection displays.
</Accordion>

### Page-Specific Sections

<Tabs>
  <Tab title="Product">
    * `main-product.liquid` - Main product page section
    * `featured-product.liquid` - Featured product showcase
    * `featured-product-information.liquid` - Product details
  </Tab>

  <Tab title="Collection">
    * `main-collection.liquid` - Collection page with filtering
    * `main-collection-list.liquid` - Collection list page
    * `collection-links.liquid` - Collection navigation
  </Tab>

  <Tab title="Blog">
    * `main-blog.liquid` - Blog listing page
    * `main-blog-post.liquid` - Article page
    * `featured-blog-posts.liquid` - Blog highlights
  </Tab>

  <Tab title="Cart">
    * `main-cart.liquid` - Shopping cart page
    * Uses `_cart-products`, `_cart-summary`, and `_cart-title` blocks
  </Tab>
</Tabs>

### Header & Footer Groups

Section groups enable modular header/footer architecture:

```json sections/header-group.json theme={null}
{
  "type": "header",
  "name": "t:names.header",
  "sections": {
    "header_announcements": {
      "type": "header-announcements",
      "blocks": {
        "announcement": {
          "type": "_announcement",
          "settings": {
            "text": "Welcome to our store",
            "font_size": "0.75rem"
          }
        }
      }
    },
    "header_section": {
      "type": "header",
      "blocks": {
        "header-logo": { "type": "_header-logo", "static": true },
        "header-menu": { "type": "_header-menu", "static": true }
      },
      "settings": {
        "logo_position": "left",
        "menu_position": "left",
        "enable_sticky_header": "always",
        "enable_transparent_header_home": false
      }
    }
  },
  "order": ["header_announcements", "header_section"]
}
```

## Blocks

Theme blocks (94 total) are prefixed with `_` and provide reusable components.

### Block Categories

<CardGroup cols={2}>
  <Card title="Content Blocks" icon="font">
    * `_heading.liquid` - Customizable headings
    * `_content.liquid` - Nested content groups
    * `_divider.liquid` - Section dividers
    * `_inline-text.liquid` - Inline typography
  </Card>

  <Card title="Media Blocks" icon="image">
    * `_image.liquid` - Responsive images
    * `_media.liquid` - Video/image media
    * `_carousel-content.liquid` - Carousel items
    * `_layered-slide.liquid` - Layered slideshows
  </Card>

  <Card title="Product Blocks" icon="shopping-cart">
    * `_product-card.liquid` - Product cards
    * `_product-card-gallery.liquid` - Product images
    * `_featured-product.liquid` - Featured products
    * `_featured-product-price.liquid` - Pricing display
  </Card>

  <Card title="Navigation Blocks" icon="bars">
    * `_header-logo.liquid` - Site logo
    * `_header-menu.liquid` - Navigation menus
    * `_footer-social-icons.liquid` - Social links
    * `_announcement.liquid` - Announcements
  </Card>
</CardGroup>

### Block Schema Example

```liquid blocks/_content.liquid theme={null}
{% capture children %}
  {% content_for 'blocks' %}
{% endcapture %}

{% render 'group', children: children, settings: block.settings, shopify_attributes: block.shopify_attributes %}

{% schema %}
{
  "name": "t:names.content",
  "tag": null,
  "blocks": [
    { "type": "@theme" },
    { "type": "@app" },
    { "type": "_divider" }
  ],
  "settings": [
    {
      "type": "select",
      "id": "horizontal_alignment_flex_direction_column",
      "label": "t:settings.alignment",
      "options": [
        { "value": "flex-start", "label": "t:options.left" },
        { "value": "center", "label": "t:options.center" },
        { "value": "flex-end", "label": "t:options.right" }
      ]
    },
    {
      "type": "range",
      "id": "gap",
      "label": "t:settings.gap",
      "min": 0,
      "max": 100,
      "default": 24
    },
    {
      "type": "checkbox",
      "id": "inherit_color_scheme",
      "label": "t:settings.inherit_color_scheme",
      "default": true
    }
  ]
}
{% endschema %}
```

<Note>
  The `_content` block is **nestable** - it accepts other theme blocks, enabling complex layouts through composition.
</Note>

## Snippets

Horizon contains 93 snippets organized by functionality.

### Core Snippets

<Accordion title="section.liquid - Universal Section Wrapper">
  ```liquid snippets/section.liquid theme={null}
  {%- doc -%}
    Renders a wrapper section

    @param {section} section - The section object
    @param {string} children - The children of the section
  {%- enddoc -%}

  <div class="section-background color-{{ section.settings.color_scheme }}"></div>
  <div
    class="section section--{{ section.settings.section_width }}"
    style="
      {% if section.settings.section_height == 'custom' %}
        --section-min-height: {{ section.settings.section_height_custom }}svh;
      {% elsif section.settings.section_height == 'full-screen' %}
        --section-min-height: 100svh;
      {% endif %}
    "
  >
    <div class="custom-section-background">
      {% render 'background-media',
        background_media: section.settings.background_media,
        background_video: section.settings.video,
        background_image: section.settings.background_image
      %}
    </div>

    <div class="border-style custom-section-content">
      {% if section.settings.toggle_overlay %}
        {% render 'overlay', settings: section.settings %}
      {% endif %}

      {{ children }}
    </div>
  </div>
  ```

  **Responsibilities:**

  * Color scheme application
  * Background media rendering
  * Overlay effects
  * Height and width management
</Accordion>

<Accordion title="group.liquid - Block Container">
  ```liquid snippets/group.liquid theme={null}
  {%- doc -%}
    Renders block content for all blocks that extend the group block.

    @param {string} children - The DOM content of the group block.
    @param {object} settings - The settings of the group block.
    @param {string} shopify_attributes - String with Shopify attributes.
  {%- enddoc -%}

  <div
    class="group-block {% if settings.inherit_color_scheme == false %}color-{{ settings.color_scheme }}{% endif %}"
    style="
      {% render 'border-override', settings: settings %}
      {% render 'spacing-style', settings: settings %}
    "
    {{ shopify_attributes }}
  >
    {%- if settings.link != blank -%}
      <a href="{{ settings.link }}" class="group-block__link"></a>
    {%- endif -%}

    <div class="group-block__media-wrapper">
      {% render 'background-media',
        background_media: settings.background_media,
        background_video: settings.video,
        background_image: settings.background_image
      %}
    </div>

    {{ children }}
  </div>
  ```
</Accordion>

<Accordion title="bento-grid.liquid - Advanced Layout System">
  Renders items in a sophisticated bento box grid:

  ```liquid snippets/bento-grid.liquid theme={null}
  {%- doc -%}
    Takes an array of HTML strings and positions them in a bento box grid.
    Bento boxes can hold up to 12 items.

    @param {string[]} items - Array of HTML strings
  {%- enddoc -%}

  {% liquid
    assign odd_item_check = items.size | modulo: 12
    if odd_item_check == 1
      assign first_box_size = 11
    else
      assign first_box_size = 12
    endif
  %}

  {% for item in items %}
    {% if forloop.first or item_modulo == 1 %}
      <div class="bento-box bento-box--items-{{ box_item_count }}">
    {% endif %}

    <div class="bento-box__item">
      {{ item }}
    </div>

    {% if forloop.last or item_modulo == 0 %}
      </div>
    {% endif %}
  {% endfor %}

  {% stylesheet %}
    .bento-box {
      display: grid;
      grid-template-columns: repeat(12, 1fr);
      grid-template-areas:
        'A A A B B B B B B C C C'
        'D D D D D D E E E F F F'
        'G G G H H H I I I I I I'
        'J J J J K K K K L L L L';
    }
  {% endstylesheet %}
  ```

  The bento grid dynamically adjusts for 1-12 items with optimized layouts.
</Accordion>

### Utility Snippets

<Tabs>
  <Tab title="Product">
    * `card-gallery.liquid` - Product image galleries
    * `collection-card.liquid` - Collection cards
    * `editorial-product-grid.liquid` - Editorial layouts
    * `add-to-cart-button.liquid` - Add to cart functionality
  </Tab>

  <Tab title="Cart">
    * `cart-products.liquid` - Cart line items
    * `cart-summary.liquid` - Cart totals and checkout
    * `cart-bubble.liquid` - Cart count indicator
    * `gift-card-recipient-form.liquid` - Gift card forms
  </Tab>

  <Tab title="Layout">
    * `background-media.liquid` - Background images/videos
    * `border-override.liquid` - Border styling
    * `gap-style.liquid` - Spacing utilities
    * `grid-density-controls.liquid` - Grid configurations
  </Tab>

  <Tab title="UI">
    * `button.liquid` - Button component
    * `checkbox.liquid` - Form checkboxes
    * `divider.liquid` - Visual dividers
    * `color-schemes.liquid` - Theme color schemes
  </Tab>
</Tabs>

## Templates

Horizon uses **JSON templates** exclusively (14 files).

### Template Structure

```json templates/product.json theme={null}
{
  "sections": {
    "main": {
      "type": "main-product",
      "blocks": {
        "vendor": { "type": "text" },
        "title": { "type": "title" },
        "price": { "type": "price" },
        "variant_picker": { "type": "variant_picker" },
        "quantity_selector": { "type": "quantity_selector" },
        "buy_buttons": { "type": "buy_buttons" }
      },
      "block_order": ["vendor", "title", "price", "variant_picker", "quantity_selector", "buy_buttons"]
    }
  },
  "order": ["main"]
}
```

### Available Templates

<CardGroup cols={3}>
  <Card title="404.json" icon="triangle-exclamation">
    Error page template
  </Card>

  <Card title="article.json" icon="newspaper">
    Blog post template
  </Card>

  <Card title="blog.json" icon="book">
    Blog listing template
  </Card>

  <Card title="cart.json" icon="shopping-cart">
    Shopping cart template
  </Card>

  <Card title="collection.json" icon="layer-group">
    Collection template
  </Card>

  <Card title="gift_card.liquid" icon="gift">
    Gift card (Liquid)
  </Card>

  <Card title="index.json" icon="house">
    Homepage template
  </Card>

  <Card title="list-collections.json" icon="list">
    All collections template
  </Card>

  <Card title="page.json" icon="file">
    Default page template
  </Card>

  <Card title="page.contact.json" icon="envelope">
    Contact page template
  </Card>

  <Card title="password.json" icon="lock">
    Password page template
  </Card>

  <Card title="product.json" icon="box">
    Product template
  </Card>

  <Card title="search.json" icon="magnifying-glass">
    Search results template
  </Card>
</CardGroup>

<Note>
  Only `gift_card.liquid` uses the Liquid format; all others are JSON for maximum flexibility.
</Note>

## Layout Files

### theme.liquid

The main layout file provides the HTML shell:

```liquid layout/theme.liquid theme={null}
<!doctype html>
<html lang="{{ request.locale.iso_code }}">
  <head>
    {%- render 'meta-tags' -%}
    {%- render 'stylesheets' -%}
    {%- render 'fonts' -%}
    {%- render 'scripts' -%}
    {%- render 'theme-styles-variables' -%}
    {%- render 'color-schemes' -%}
    {{ content_for_header }}
  </head>

  <body class="page-width-{{ settings.page_width }}">
    <div id="header-group">
      {% sections 'header-group' %}
    </div>

    <main id="MainContent" role="main">
      {{ content_for_layout }}
    </main>

    <footer>
      {% sections 'footer-group' %}
    </footer>

    {% render 'search-modal' %}
    {% if settings.quick_add %}
      {% render 'quick-add-modal' %}
    {% endif %}
  </body>
</html>
```

### password.liquid

Special layout for password-protected stores.

## Assets

Horizon includes 100+ asset files:

<Tabs>
  <Tab title="CSS">
    * `base.css` - Core styles, CSS custom properties
    * Component-specific styles in sections/snippets
    * Scoped styles using `{% stylesheet %}` tags
  </Tab>

  <Tab title="JavaScript">
    * `component.js` - Base component class
    * `events.js` - Custom event system
    * `cart-drawer.js` - Cart functionality
    * `header-drawer.js` - Mobile navigation
    * `product-gallery.js` - Product image galleries
    * Web Components for interactive features
  </Tab>

  <Tab title="Other">
    * Font files
    * Placeholder images
    * Icons and graphics
  </Tab>
</Tabs>

## Best Practices

<AccordionGroup>
  <Accordion title="Use theme blocks over custom sections">
    Theme blocks are more flexible and reusable. Prefer composing layouts with blocks rather than creating monolithic sections.
  </Accordion>

  <Accordion title="Leverage snippets for reusability">
    Extract common patterns into snippets. Use the `{%- doc -%}` tag to document parameters.
  </Accordion>

  <Accordion title="Follow naming conventions">
    * Sections: descriptive names (`hero.liquid`, `main-product.liquid`)
    * Blocks: underscore prefix (`_heading.liquid`, `_content.liquid`)
    * Snippets: functionality-based names (`section.liquid`, `bento-grid.liquid`)
  </Accordion>

  <Accordion title="Use JSON templates">
    JSON templates provide better flexibility and enable merchants to customize layouts without code.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Liquid Storefronts" icon="droplet" href="/architecture/liquid-storefronts">
    Learn about modern Liquid features
  </Card>

  <Card title="Theme Blocks" icon="cube" href="/architecture/theme-blocks">
    Deep dive into theme blocks
  </Card>

  <Card title="Development Guide" icon="code" href="/development/setup">
    Set up your development environment
  </Card>

  <Card title="Component Reference" icon="book" href="/components/sections/overview">
    Browse all sections and blocks
  </Card>
</CardGroup>