Shopify Schema Design
Schema Structure
The {% schema %} tag defines how a section appears in the theme editor:
{ "name": "Section Name", "tag": "section", "class": "section-class", "limit": 1, "settings": [...], "blocks": [...], "presets": [...] }
Setting Types
Text Input
{ "type": "text", "id": "heading", "label": "Heading", "default": "Default text", "info": "Helpful description", "placeholder": "Enter text here" }
Textarea
{ "type": "textarea", "id": "description", "label": "Description", "default": "Default description" }
Rich Text
{ "type": "richtext", "id": "content", "label": "Content", "default": "<p>Default rich text content</p>" }
Number / Range
{ "type": "range", "id": "padding", "label": "Padding", "min": 0, "max": 100, "step": 4, "unit": "px", "default": 40, "info": "Section padding in pixels" }
Checkbox
{ "type": "checkbox", "id": "show_vendor", "label": "Show Product Vendor", "default": true, "info": "Display vendor name on product cards" }
Select / Dropdown
{ "type": "select", "id": "layout", "label": "Layout Style", "options": [ { "value": "grid", "label": "Grid" }, { "value": "carousel", "label": "Carousel" }, { "value": "list", "label": "List" } ], "default": "grid", "info": "Choose how products are displayed" }
Radio Buttons
{ "type": "radio", "id": "alignment", "label": "Text Alignment", "options": [ { "value": "left", "label": "Left" }, { "value": "center", "label": "Center" }, { "value": "right", "label": "Right" } ], "default": "center" }
Color Picker
{ "type": "color", "id": "bg_color", "label": "Background Color", "default": "#ffffff", "info": "Section background color" }
Color Background
{ "type": "color_background", "id": "background_gradient", "label": "Background Gradient", "info": "Supports solid colors and gradients" }
Image Picker
{ "type": "image_picker", "id": "image", "label": "Image", "info": "Recommended size: 1600 x 900 px" }
Font Picker
{ "type": "font_picker", "id": "heading_font", "label": "Heading Font", "default": "assistant_n4", "info": "Choose font for headings" }
Collection Picker
{ "type": "collection", "id": "collection", "label": "Collection" }
Product Picker
{ "type": "product", "id": "featured_product", "label": "Featured Product" }
Product List
{ "type": "product_list", "id": "products", "label": "Products", "limit": 12, "info": "Select up to 12 products" }
Collection List
{ "type": "collection_list", "id": "collections", "label": "Collections", "limit": 8 }
Blog Picker
{ "type": "blog", "id": "blog", "label": "Blog" }
Article Picker
{ "type": "article", "id": "article", "label": "Article" }
Page Picker
{ "type": "page", "id": "page", "label": "Page" }
Link / URL
{ "type": "url", "id": "button_link", "label": "Button Link", "info": "Link to internal page or external URL" }
Video URL
{ "type": "video_url", "id": "video", "label": "Video URL", "accept": ["youtube", "vimeo"], "info": "Supports YouTube and Vimeo" }
HTML
{ "type": "html", "id": "custom_html", "label": "Custom HTML", "info": "Add custom HTML code" }
Liquid
{ "type": "liquid", "id": "custom_liquid", "label": "Custom Liquid", "info": "Add custom Liquid code" }
Organizational Elements
Header
{ "type": "header", "content": "Section Heading" }
Paragraph
{ "type": "paragraph", "content": "Helpful information or instructions for merchants." }
Complete Schema Example
{% schema %} { "name": "Product Grid", "tag": "section", "class": "product-grid-section", "settings": [ { "type": "header", "content": "Content" }, { "type": "text", "id": "heading", "label": "Heading", "default": "Featured Products" }, { "type": "richtext", "id": "description", "label": "Description" }, { "type": "collection", "id": "collection", "label": "Collection" }, { "type": "range", "id": "products_count", "label": "Number of Products", "min": 2, "max": 12, "step": 1, "default": 4 }, { "type": "header", "content": "Layout" }, { "type": "select", "id": "layout", "label": "Layout Style", "options": [ { "value": "grid", "label": "Grid" }, { "value": "carousel", "label": "Carousel" } ], "default": "grid" }, { "type": "select", "id": "columns_desktop", "label": "Desktop Columns", "options": [ { "value": "2", "label": "2" }, { "value": "3", "label": "3" }, { "value": "4", "label": "4" } ], "default": "4" }, { "type": "select", "id": "columns_mobile", "label": "Mobile Columns", "options": [ { "value": "1", "label": "1" }, { "value": "2", "label": "2" } ], "default": "1" }, { "type": "header", "content": "Product Card" }, { "type": "checkbox", "id": "show_vendor", "label": "Show Product Vendor", "default": false }, { "type": "checkbox", "id": "show_quick_view", "label": "Enable Quick View", "default": true }, { "type": "header", "content": "Colors" }, { "type": "color", "id": "bg_color", "label": "Background Color", "default": "#ffffff" }, { "type": "color", "id": "text_color", "label": "Text Color", "default": "#000000" }, { "type": "header", "content": "Spacing" }, { "type": "range", "id": "padding_top", "label": "Top Spacing", "min": 0, "max": 100, "step": 4, "unit": "px", "default": 40 }, { "type": "range", "id": "padding_bottom", "label": "Bottom Spacing", "min": 0, "max": 100, "step": 4, "unit": "px", "default": 40 } ], "blocks": [ { "type": "featured_product", "name": "Featured Product", "settings": [ { "type": "product", "id": "product", "label": "Product" } ] } ], "presets": [ { "name": "Product Grid", "settings": { "heading": "Featured Products", "products_count": 4 } } ] } {% endschema %}
Blocks Configuration
Basic Blocks
{ "blocks": [ { "type": "heading", "name": "Heading", "settings": [ { "type": "text", "id": "text", "label": "Text", "default": "Heading" } ] }, { "type": "paragraph", "name": "Paragraph", "settings": [ { "type": "richtext", "id": "content", "label": "Content" } ] } ], "max_blocks": 10 }
Accept All Theme Blocks
{ "blocks": [ { "type": "@theme" } ] }
Accept App Blocks
{ "blocks": [ { "type": "@app" } ] }
Presets
Basic Preset
{ "presets": [ { "name": "Hero Banner" } ] }
Preset with Default Settings
{ "presets": [ { "name": "Product Grid", "settings": { "heading": "Featured Products", "products_count": 4, "columns_desktop": "4" } } ] }
Preset with Blocks
{ "presets": [ { "name": "Testimonials", "blocks": [ { "type": "testimonial" }, { "type": "testimonial" }, { "type": "testimonial" } ] } ] }
Best Practices
- Group Related Settings with Headers
{ "settings": [ { "type": "header", "content": "Content Settings" }, { "type": "text", "id": "heading", "label": "Heading" }, { "type": "header", "content": "Layout Settings" }, { "type": "select", "id": "columns", "label": "Columns" } ] }
- Always Provide Defaults
{ "type": "text", "id": "heading", "label": "Heading", "default": "Default Heading" ← Always provide! }
- Add Info Text for Complex Settings
{ "type": "range", "id": "products_count", "label": "Number of Products", "min": 2, "max": 12, "default": 4, "info": "Maximum number of products to display from the selected collection" }
- Use Appropriate Input Types
-
Text/numbers → text , textarea , number , range
-
True/false → checkbox
-
Multiple options → select , radio
-
Resources → collection , product , image_picker
-
Colors → color , color_background
- Set Reasonable Limits
{ "type": "range", "id": "padding", "min": 0, ← Minimum value "max": 100, ← Maximum value "step": 4, ← Increment "default": 40 ← Sensible default }
- Include Presets for Quick Setup
{ "presets": [ { "name": "Section Name", "settings": { "heading": "Default Heading", "show_feature": true }, "blocks": [ { "type": "block_type" } ] } ] }
Create schemas that make section customization intuitive and efficient for merchants.