Layout Customization

Overview

Horizon provides flexible layout options that control page width, spacing, borders, and structural elements throughout your theme. These settings create a consistent visual structure across all pages.

Page Width

Control the maximum width of your site’s content:

page_width

select

default:"narrow"

Maximum page content width

narrow - Narrow width (~1200px) - Ideal for focused, readable content
normal - Standard width (~1400px) - Balanced for most stores
wide - Wide width (~1600px) - Expansive for catalog-heavy sites

Page Width Variables

:root {
  --page-width-narrow: 1200px;
  --page-width-normal: 1400px;
  --page-width-wide: 1600px;
  --page-width: var(--page-width-narrow); /* Based on setting */
}

When to Use Each Width

Narrow

Best for:

Content-focused sites
Blogs and articles
Minimal product catalogs
Better readability

Normal

Best for:

Standard e-commerce
Balanced layouts
Mixed content types
Most use cases

Wide

Best for:

Large product catalogs
Image-heavy content
Multiple columns
Showcasing collections

Button Styles

Configure the appearance of buttons throughout your theme.

Primary Buttons

primary_button_border_width

range

default:"0"

Border width in pixels

Range: 0-4px
Default: 0px (no border)

button_border_radius_primary

range

default:"100"

Corner roundness

Range: 0-100px
Default: 100px (pill-shaped)

type_font_button_primary

select

default:"body"

Font family for primary buttons

body - Body font
accent - Accent font

button_text_case_primary

select

default:"default"

Text transformation

default - No transformation
uppercase - ALL CAPS

Secondary Buttons

secondary_button_border_width

range

default:"1"

Border width in pixels

Range: 0-4px
Default: 1px

button_border_radius_secondary

range

default:"100"

Corner roundness

Range: 0-100px
Default: 100px (pill-shaped)

type_font_button_secondary

select

default:"body"

Font family for secondary buttons

body - Body font
accent - Accent font

button_text_case_secondary

select

default:"default"

Text transformation

default - No transformation
uppercase - ALL CAPS

Pills

Pills are small, rounded elements used for tags, filters, and navigation:

pills_border_radius

range

default:"40"

Corner roundness for pill elements

Range: 0-40px
Default: 40px (fully rounded)

Border Styles

Control borders across various components.

Cart Thumbnails

cart_thumbnail_border

select

default:"none"

Border style for product images in cart

none - No border
solid - Solid border

cart_thumbnail_border_width

range

default:"1"

Border thickness (0-10px)

cart_thumbnail_border_opacity

range

default:"50"

Border transparency (0-100%)

cart_thumbnail_border_radius

range

default:"0"

Corner roundness (0-100px)

Drawers

drawer_border

select

default:"none"

Border style for slide-out drawers

none - No border
solid - Solid border

drawer_border_width

range

default:"1"

Border thickness (0-10px)

drawer_border_opacity

range

default:"50"

Border transparency (0-100%)

Popovers

Border style for popovers and modals

none - No border
solid - Solid border

Border thickness (0-10px)

Border transparency (0-100%)

Corner roundness (0-16px)

Corner Radius

Horizon uses consistent border radius values across components:

Buttons

Primary: 0-100px (default: 100px)
Secondary: 0-100px (default: 100px)
Pills: 0-40px (default: 40px)

Inputs & Forms

Input fields: 0-32px (default: 8px)
Variant buttons: 0-100px (default: 8px)

Media

Product images: 0-32px (default: 0px)
Card corners: 0-16px (default: 0px)
Cart thumbnails: 0-100px (default: 0px)

Containers

Popovers: 0-16px (default: 8px)
Badges: 0-100px (default: 40px)

Spacing System

Horizon uses a consistent spacing scale:

Spacing Variables

:root {
  --spacing-xs: 4px;
  --spacing-sm: 8px;
  --spacing-md: 16px;
  --spacing-lg: 24px;
  --spacing-xl: 32px;
  --spacing-2xl: 48px;
  --spacing-3xl: 64px;
  --spacing-4xl: 96px;
}

Applying Spacing

Use the spacing snippet for consistent margins and padding:

Spacing Snippet

{% render 'spacing-style',
  padding_top: 'medium',
  padding_bottom: 'medium',
  margin_top: 'none',
  margin_bottom: 'none'
%}

Layout Utilities

Grid System

Horizon includes a flexible grid system:

Grid Layout

<div class="grid grid--2-col grid--tablet-1-col">
  <div class="grid__item">Column 1</div>
  <div class="grid__item">Column 2</div>
</div>

Grid classes:

.grid--1-col through .grid--6-col - Desktop columns
.grid--tablet-{n}-col - Tablet breakpoint
.grid--mobile-1-col - Mobile breakpoint
.grid--gap-{size} - Column gap size

Container Widths

Container Types

<div class="page-width">Full page width container</div>
<div class="container container--narrow">Narrow container</div>
<div class="container container--medium">Medium container</div>

Responsive Utilities

Responsive Classes

<div class="hide-mobile">Hidden on mobile</div>
<div class="hide-tablet">Hidden on tablet</div>
<div class="hide-desktop">Hidden on desktop</div>
<div class="show-mobile">Shown only on mobile</div>

Section Layouts

Customize individual section layouts:

Section Layout Schema

{
  "settings": [
    {
      "type": "select",
      "id": "layout",
      "label": "Layout",
      "options": [
        {"value": "full-width", "label": "Full width"},
        {"value": "contained", "label": "Contained"},
        {"value": "narrow", "label": "Narrow"}
      ],
      "default": "contained"
    },
    {
      "type": "range",
      "id": "padding_top",
      "min": 0,
      "max": 100,
      "step": 4,
      "unit": "px",
      "label": "Top padding",
      "default": 36
    },
    {
      "type": "range",
      "id": "padding_bottom",
      "min": 0,
      "max": 100,
      "step": 4,
      "unit": "px",
      "label": "Bottom padding",
      "default": 36
    }
  ]
}

Variant Picker Layout

Style variant selection buttons:

variant_button_border_width

range

default:"1"

Border width for variant buttons (0-4px)

variant_button_radius

range

default:"8"

Corner roundness (0-100px)

variant_button_width

select

default:"equal-width-buttons"

Button width behavior

default-width-buttons - Fit to content
equal-width-buttons - Equal width for all buttons

Shadow Effects

drawer_drop_shadow

boolean

default:"false"

Add drop shadow to drawer elements

popover_drop_shadow

boolean

default:"true"

Add drop shadow to popovers and modals

Shadow values are defined per color scheme:

Shadow Variables

.color-scheme-1 {
  --shadow-drawer: 0px 4px 20px rgb(var(--color-shadow-rgb) / 0.15);
  --shadow-popover: 0px 4px 20px rgb(var(--color-shadow-rgb) / 0.15);
  --shadow-blur: 20px;
}

Layout Examples

Full-Width Hero Section

Full-Width Layout

<section class="section section--full-width" 
         style="--padding-top: {{ section.settings.padding_top }}px;">
  <div class="hero">
    {% render 'background-media', media: section.settings.image %}
    <div class="hero__content page-width">
      <h1>{{ section.settings.heading }}</h1>
    </div>
  </div>
</section>

Contained Content Section

Contained Layout

<section class="section" 
         style="--padding-top: 48px; --padding-bottom: 48px;">
  <div class="page-width">
    <div class="section__header">
      <h2>{{ section.settings.heading }}</h2>
    </div>
    <div class="section__content">
      {{ section.settings.content }}
    </div>
  </div>
</section>

Two-Column Layout

<div class="page-width">
  <div class="grid grid--2-col grid--tablet-1-col grid--gap-lg">
    <div class="grid__item">
      <h3>Column 1</h3>
      <p>Content for first column</p>
    </div>
    <div class="grid__item">
      <h3>Column 2</h3>
      <p>Content for second column</p>
    </div>
  </div>
</div>

Best Practices

Consistent Spacing

Use the theme’s spacing scale consistently:

Stick to predefined spacing values
Maintain vertical rhythm
Use the spacing snippet for sections

Responsive Design

Always test layouts on multiple devices:

Use responsive grid classes
Adjust padding for mobile
Hide/show elements appropriately

Visual Hierarchy

Create clear visual structure:

Use whitespace effectively
Group related content
Separate sections with padding/borders

Button Consistency

Maintain consistent button styles:

Use primary buttons for main actions
Secondary buttons for alternative actions
Keep border radius consistent

Layout Snippet Reference

Section Wrapper

snippets/section.liquid

<section 
  class="section section--{{ section.settings.layout }}"
  {% render 'spacing-style', 
    padding_top: section.settings.padding_top,
    padding_bottom: section.settings.padding_bottom %}
>
  {% if section.settings.layout == 'full-width' %}
    {{ content }}
  {% else %}
    <div class="page-width">
      {{ content }}
    </div>
  {% endif %}
</section>

Spacing Helper

snippets/spacing-style.liquid

style="
  {% if padding_top %}--padding-top: {{ padding_top }}px;{% endif %}
  {% if padding_bottom %}--padding-bottom: {{ padding_bottom }}px;{% endif %}
  {% if margin_top %}--margin-top: {{ margin_top }}px;{% endif %}
  {% if margin_bottom %}--margin-bottom: {{ margin_bottom }}px;{% endif %}
"

Theme Settings

Configure page width and global layout options

Color Schemes

Apply colors to layout elements

Typography

Control text sizing within layouts

Overview

Core Concepts

Development

Customization

Features

​Overview

​Page Width

​When to Use Each Width

Narrow

Normal

Wide

​Button Styles

​Primary Buttons

​Secondary Buttons

​Pills

​Border Styles

​Cart Thumbnails

​Drawers

​Popovers

​Corner Radius

​Spacing System

​Applying Spacing

​Layout Utilities

​Grid System

​Container Widths

​Responsive Utilities

​Section Layouts

​Variant Picker Layout

​Shadow Effects

​Layout Examples

​Full-Width Hero Section

​Contained Content Section

​Two-Column Layout

​Best Practices

​Layout Snippet Reference

​Section Wrapper

​Spacing Helper

​Related Pages

Theme Settings

Color Schemes

Typography

Build docs developers (and LLMs) love

Overview

Page Width

When to Use Each Width

Button Styles

Primary Buttons

Secondary Buttons

Pills

Border Styles

Cart Thumbnails

Drawers

Popovers

Corner Radius

Spacing System

Applying Spacing

Layout Utilities

Grid System

Container Widths

Responsive Utilities

Section Layouts

Variant Picker Layout

Shadow Effects

Layout Examples

Full-Width Hero Section

Contained Content Section

Two-Column Layout

Best Practices

Layout Snippet Reference

Section Wrapper

Spacing Helper

Related Pages