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

# Layout Customization

> Configure page layouts, spacing, and structural elements in Horizon

## 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:

<ParamField path="page_width" type="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
</ParamField>

```css Page Width Variables theme={null}
: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

<CardGroup cols={3}>
  <Card title="Narrow" icon="minimize">
    **Best for:**

    * Content-focused sites
    * Blogs and articles
    * Minimal product catalogs
    * Better readability
  </Card>

  <Card title="Normal" icon="arrows-left-right">
    **Best for:**

    * Standard e-commerce
    * Balanced layouts
    * Mixed content types
    * Most use cases
  </Card>

  <Card title="Wide" icon="maximize">
    **Best for:**

    * Large product catalogs
    * Image-heavy content
    * Multiple columns
    * Showcasing collections
  </Card>
</CardGroup>

## Button Styles

Configure the appearance of buttons throughout your theme.

### Primary Buttons

<ParamField path="primary_button_border_width" type="range" default="0">
  Border width in pixels

  * **Range:** 0-4px
  * **Default:** 0px (no border)
</ParamField>

<ParamField path="button_border_radius_primary" type="range" default="100">
  Corner roundness

  * **Range:** 0-100px
  * **Default:** 100px (pill-shaped)
</ParamField>

<ParamField path="type_font_button_primary" type="select" default="body">
  Font family for primary buttons

  * `body` - Body font
  * `accent` - Accent font
</ParamField>

<ParamField path="button_text_case_primary" type="select" default="default">
  Text transformation

  * `default` - No transformation
  * `uppercase` - ALL CAPS
</ParamField>

### Secondary Buttons

<ParamField path="secondary_button_border_width" type="range" default="1">
  Border width in pixels

  * **Range:** 0-4px
  * **Default:** 1px
</ParamField>

<ParamField path="button_border_radius_secondary" type="range" default="100">
  Corner roundness

  * **Range:** 0-100px
  * **Default:** 100px (pill-shaped)
</ParamField>

<ParamField path="type_font_button_secondary" type="select" default="body">
  Font family for secondary buttons

  * `body` - Body font
  * `accent` - Accent font
</ParamField>

<ParamField path="button_text_case_secondary" type="select" default="default">
  Text transformation

  * `default` - No transformation
  * `uppercase` - ALL CAPS
</ParamField>

### Pills

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

<ParamField path="pills_border_radius" type="range" default="40">
  Corner roundness for pill elements

  * **Range:** 0-40px
  * **Default:** 40px (fully rounded)
</ParamField>

## Border Styles

Control borders across various components.

### Cart Thumbnails

<ParamField path="cart_thumbnail_border" type="select" default="none">
  Border style for product images in cart

  * `none` - No border
  * `solid` - Solid border
</ParamField>

<ParamField path="cart_thumbnail_border_width" type="range" default="1">
  Border thickness (0-10px)
</ParamField>

<ParamField path="cart_thumbnail_border_opacity" type="range" default="50">
  Border transparency (0-100%)
</ParamField>

<ParamField path="cart_thumbnail_border_radius" type="range" default="0">
  Corner roundness (0-100px)
</ParamField>

### Drawers

<ParamField path="drawer_border" type="select" default="none">
  Border style for slide-out drawers

  * `none` - No border
  * `solid` - Solid border
</ParamField>

<ParamField path="drawer_border_width" type="range" default="1">
  Border thickness (0-10px)
</ParamField>

<ParamField path="drawer_border_opacity" type="range" default="50">
  Border transparency (0-100%)
</ParamField>

### Popovers

<ParamField path="popover_border" type="select" default="solid">
  Border style for popovers and modals

  * `none` - No border
  * `solid` - Solid border
</ParamField>

<ParamField path="popover_border_width" type="range" default="1">
  Border thickness (0-10px)
</ParamField>

<ParamField path="popover_border_opacity" type="range" default="50">
  Border transparency (0-100%)
</ParamField>

<ParamField path="popover_border_radius" type="range" default="8">
  Corner roundness (0-16px)
</ParamField>

## Corner Radius

Horizon uses consistent border radius values across components:

<AccordionGroup>
  <Accordion title="Buttons" icon="rectangle-wide">
    * **Primary:** 0-100px (default: 100px)
    * **Secondary:** 0-100px (default: 100px)
    * **Pills:** 0-40px (default: 40px)
  </Accordion>

  <Accordion title="Inputs & Forms" icon="input-text">
    * **Input fields:** 0-32px (default: 8px)
    * **Variant buttons:** 0-100px (default: 8px)
  </Accordion>

  <Accordion title="Media" icon="image">
    * **Product images:** 0-32px (default: 0px)
    * **Card corners:** 0-16px (default: 0px)
    * **Cart thumbnails:** 0-100px (default: 0px)
  </Accordion>

  <Accordion title="Containers" icon="square">
    * **Popovers:** 0-16px (default: 8px)
    * **Badges:** 0-100px (default: 40px)
  </Accordion>
</AccordionGroup>

## Spacing System

Horizon uses a consistent spacing scale:

```css Spacing Variables theme={null}
: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:

```liquid Spacing Snippet theme={null}
{% 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:

```html Grid Layout theme={null}
<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

```liquid Container Types theme={null}
<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

```html Responsive Classes theme={null}
<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:

```json Section Layout Schema theme={null}
{
  "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:

<ParamField path="variant_button_border_width" type="range" default="1">
  Border width for variant buttons (0-4px)
</ParamField>

<ParamField path="variant_button_radius" type="range" default="8">
  Corner roundness (0-100px)
</ParamField>

<ParamField path="variant_button_width" type="select" default="equal-width-buttons">
  Button width behavior

  * `default-width-buttons` - Fit to content
  * `equal-width-buttons` - Equal width for all buttons
</ParamField>

## Shadow Effects

<ParamField path="drawer_drop_shadow" type="boolean" default="false">
  Add drop shadow to drawer elements
</ParamField>

<ParamField path="popover_drop_shadow" type="boolean" default="true">
  Add drop shadow to popovers and modals
</ParamField>

Shadow values are defined per color scheme:

```css Shadow Variables theme={null}
.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

```liquid Full-Width Layout theme={null}
<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

```liquid Contained Layout theme={null}
<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

```liquid Two-Column Layout theme={null}
<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

<AccordionGroup>
  <Accordion title="Consistent Spacing" icon="ruler">
    Use the theme's spacing scale consistently:

    * Stick to predefined spacing values
    * Maintain vertical rhythm
    * Use the spacing snippet for sections
  </Accordion>

  <Accordion title="Responsive Design" icon="mobile">
    Always test layouts on multiple devices:

    * Use responsive grid classes
    * Adjust padding for mobile
    * Hide/show elements appropriately
  </Accordion>

  <Accordion title="Visual Hierarchy" icon="layer-group">
    Create clear visual structure:

    * Use whitespace effectively
    * Group related content
    * Separate sections with padding/borders
  </Accordion>

  <Accordion title="Button Consistency" icon="square">
    Maintain consistent button styles:

    * Use primary buttons for main actions
    * Secondary buttons for alternative actions
    * Keep border radius consistent
  </Accordion>
</AccordionGroup>

## Layout Snippet Reference

### Section Wrapper

```liquid snippets/section.liquid theme={null}
<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

```liquid snippets/spacing-style.liquid theme={null}
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 %}
"
```

## Related Pages

<CardGroup cols={2}>
  <Card title="Theme Settings" icon="gear" href="/customization/settings">
    Configure page width and global layout options
  </Card>

  <Card title="Color Schemes" icon="palette" href="/customization/color-schemes">
    Apply colors to layout elements
  </Card>

  <Card title="Typography" icon="font" href="/customization/typography">
    Control text sizing within layouts
  </Card>
</CardGroup>