Schema Configuration

Schema Overview

Schema defines the Template Customizer UI, allowing users to customize templates without editing code. The system is compatible with Shopify's sections schema, using the same input field names.

Structure

Basic Schema

{
  "sections": [
    {
      "id": "section_id",
      "name": "Section Name",
      "info": "Section description",
      "settings": [
        // Input fields here
      ]
    }
  ]
}

Section Properties

• id: Unique identifier for accessing values in Liquid
• name: Display name in customizer
• info: Help text for the section
• settings: Array of input fields

Input Types

Text

Single-line text input:

{
  "id": "heading_text",
  "type": "text",
  "label": "Heading",
  "default": "Invoice",
  "placeholder": "Enter heading text"
}

Textarea

Multi-line text input:

{
  "id": "notes",
  "type": "textarea",
  "label": "Notes",
  "default": "Thank you for your business",
  "placeholder": "Enter notes"
}

Richtext

Formatted text with HTML support:

{
  "id": "footer_message",
  "type": "richtext",
  "label": "Footer Message",
  "default": "<p>Terms and conditions apply</p>"
}

Number

Numeric input:

{
  "id": "line_height",
  "type": "number",
  "label": "Line Height",
  "default": 1.5,
  "info": "Line height multiplier"
}

Checkbox

Boolean toggle:

{
  "id": "show_logo",
  "type": "checkbox",
  "label": "Show Logo",
  "default": true
}

Range

Slider with min/max values:

{
  "id": "font_size",
  "type": "range",
  "label": "Font Size",
  "min": 10,
  "max": 24,
  "default": 14,
  "suffix": "px"
}

Select

Dropdown menu:

{
  "id": "alignment",
  "type": "select",
  "label": "Text Alignment",
  "default": "left",
  "options": [
    { "value": "left", "label": "Left" },
    { "value": "center", "label": "Center" },
    { "value": "right", "label": "Right" }
  ]
}

Color

Color picker:

{
  "id": "primary_color",
  "type": "color",
  "label": "Primary Color",
  "default": "#000000"
}

Image Picker

Image selection from media library:

{
  "id": "logo",
  "type": "image_picker",
  "label": "Company Logo",
  "default": "defaults:store_logo"
}

Font Picker

Font family selection:

{
  "id": "body_font",
  "type": "font_picker",
  "label": "Body Font",
  "default": {
    "name": "Oswald",
    "url": "https://fonts.googleapis.com/css2?family=Oswald&display=swap"
  }
}

Schema:

• type: "font_picker"
• default: Object with:
  • name: Font family name (string, required)
  • url: Font loading URL, e.g., Google Fonts (string, required)

Liquid value: Object with name and url properties

{
  "name": "Oswald",
  "url": "https://fonts.googleapis.com/css2?family=Oswald&display=swap"
}

Usage: Load font with link tag

<link rel="stylesheet" href="{{ config.typography.body_font.url }}">

<style>
  body {
    font-family: '{{ config.typography.body_font.name }}', sans-serif;
  }
</style>

Header

Section divider (no input):

{
  "type": "header",
  "content": "Typography Settings"
}

Complete Example

{
  "sections": [
    {
      "id": "branding",
      "name": "Branding",
      "info": "Logo and company details",
      "settings": [
        {
          "type": "header",
          "content": "Logo Settings"
        },
        {
          "id": "show_logo",
          "type": "checkbox",
          "label": "Display Logo",
          "default": true
        },
        {
          "id": "logo",
          "type": "image_picker",
          "label": "Logo Image",
          "default": "defaults:store_logo"
        },
        {
          "id": "logo_width",
          "type": "range",
          "label": "Logo Width",
          "min": 50,
          "max": 200,
          "default": 100,
          "suffix": "px"
        }
      ]
    },
    {
      "id": "typography",
      "name": "Typography",
      "info": "Font and text settings",
      "settings": [
        {
          "id": "heading_font",
          "type": "font_picker",
          "label": "Heading Font",
          "default": {
            "name": "Helvetica",
            "url": "https://fonts.googleapis.com/css2?family=Helvetica&display=swap"
          }
        },
        {
          "id": "heading_size",
          "type": "range",
          "label": "Heading Size",
          "min": 14,
          "max": 32,
          "default": 20,
          "suffix": "px"
        },
        {
          "id": "heading_color",
          "type": "color",
          "label": "Heading Color",
          "default": "#000000"
        }
      ]
    }
  ]
}

Using in Liquid

Access schema values through the config variable:

{% if config.branding.show_logo %}
  <img src="{{ config.branding.logo }}" 
       style="width: {{ config.branding.logo_width }}px">
{% endif %}

<link rel="stylesheet" href="{{ config.typography.heading_font.url }}">

<style>
  h1 {
    font-family: '{{ config.typography.heading_font.name }}', sans-serif;
    font-size: {{ config.typography.heading_size }}px;
    color: {{ config.typography.heading_color }};
  }
</style>

Field Properties

Common Properties

All input types support:

• id: Unique identifier (required)
• type: Input type (required)
• label: Display label
• default: Default value
• info: Help text shown below input

Type-Specific Properties

Range:

• min: Minimum value
• max: Maximum value
• suffix: Unit display (e.g., "px", "%")
• prefix: Prefix display (e.g., "$")

Select:

• options: Array of {value, label} objects

Text/Textarea:

• placeholder: Placeholder text

Best Practices

• Group related settings in sections
• Use descriptive IDs that indicate purpose
• Provide sensible defaults
• Add info text for complex settings
• Use headers to organize long sections
• Keep section count reasonable (5-10 sections)