Input Settings Reference

This page provides a complete reference for all input setting types available in section and block schemas.

Quick Reference

Category	Types
Text	text, textarea, richtext, inline_richtext, html
Selection	select, radio, checkbox
Numeric	range, number
Color	color, color_background, color_scheme
Font	font_picker
Media	image_picker, video, video_url
Resources	product, product_list, collection, collection_list, blog, article, page, link_list
Link	url
Informational	header, paragraph

Text Settings

text

Single-line text input.

{
  "type": "text",
  "id": "heading",
  "label": "Heading",
  "default": "Welcome",
  "placeholder": "Enter heading text",
  "info": "Appears at the top of the section"
}

Properties:

Property	Type	Description
`default`	string	Default value
`placeholder`	string	Placeholder text
`info`	string	Help text below input

Output: string

textarea

Multi-line text input.

{
  "type": "textarea",
  "id": "announcement",
  "label": "Announcement text",
  "default": "Free shipping on orders over $50",
  "placeholder": "Enter your message"
}

Output: string (may contain newlines)

richtext

Full WYSIWYG editor with formatting options.

{
  "type": "richtext",
  "id": "content",
  "label": "Content",
  "default": "<p>Welcome to our store!</p>"
}

Output: string (HTML) Supported formatting:

Bold, italic, underline
Links
Lists (ordered/unordered)
Headings

inline_richtext

Single-line rich text (limited formatting).

{
  "type": "inline_richtext",
  "id": "title",
  "label": "Title",
  "default": "Shop <em>New Arrivals</em>"
}

Output: string (HTML, inline elements only) Supported formatting:

Bold, italic
Links

html

Raw HTML input.

{
  "type": "html",
  "id": "embed_code",
  "label": "Embed code",
  "info": "Paste embed code from third-party services"
}

Output: string (unescaped HTML)

HTML settings render without escaping. Only use for trusted inputs like embed codes.

Selection Settings

select

Dropdown menu.

{
  "type": "select",
  "id": "image_ratio",
  "label": "Image aspect ratio",
  "options": [
    { "value": "adapt", "label": "Adapt to image" },
    { "value": "portrait", "label": "Portrait (2:3)" },
    { "value": "square", "label": "Square (1:1)" },
    { "value": "landscape", "label": "Landscape (4:3)" }
  ],
  "default": "adapt",
  "info": "Affects how product images are cropped"
}

Output: string (selected value)

radio

Radio button group (visible options).

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

Output: string (selected value)

Use radio for 2-4 options that should all be visible. Use select for more options.

checkbox

Boolean toggle.

{
  "type": "checkbox",
  "id": "show_vendor",
  "label": "Show vendor",
  "default": true,
  "info": "Display the product vendor below the title"
}

Output: boolean

{% if section.settings.show_vendor %}
  <p>{{ product.vendor }}</p>
{% endif %}

Numeric Settings

range

Slider with defined range.

{
  "type": "range",
  "id": "products_per_row",
  "label": "Products per row",
  "min": 2,
  "max": 6,
  "step": 1,
  "unit": "",
  "default": 4
}

Properties:

Property	Type	Required	Description
`min`	number	Yes	Minimum value
`max`	number	Yes	Maximum value
`step`	number	Yes	Increment step
`unit`	string	No	Unit label (px, %, em, etc.)
`default`	number	Yes	Default value

Output: number Common patterns:

// Spacing (pixels)
{ "min": 0, "max": 100, "step": 4, "unit": "px", "default": 16 }

// Percentage
{ "min": 0, "max": 100, "step": 5, "unit": "%", "default": 100 }

// Opacity
{ "min": 0, "max": 100, "step": 5, "unit": "%", "default": 100 }

// Count
{ "min": 1, "max": 12, "step": 1, "default": 4 }

number

Free numeric input (no slider).

{
  "type": "number",
  "id": "animation_delay",
  "label": "Animation delay (ms)",
  "default": 200
}

Output: number

Color Settings

color

Standard color picker.

{
  "type": "color",
  "id": "text_color",
  "label": "Text color",
  "default": "#000000"
}

Output: string (hex color or transparent)

<style>
  .section-{{ section.id }} {
    color: {{ section.settings.text_color }};
  }
</style>

color_background

Color picker with gradient support.

{
  "type": "color_background",
  "id": "background",
  "label": "Background",
  "default": "#ffffff"
}

Output: string (hex color OR CSS gradient)

<style>
  .section-{{ section.id }} {
    background: {{ section.settings.background }};
  }
</style>

color_scheme

Theme color scheme selector.

{
  "type": "color_scheme",
  "id": "color_scheme",
  "label": "Color scheme",
  "default": "scheme-1"
}

Output: string (scheme ID) Color schemes are defined in settings_schema.json and create CSS custom properties.

<section class="color-{{ section.settings.color_scheme }}">
  <!-- Inherits colors from scheme -->
</section>

Font Settings

font_picker

Google Fonts selector.

{
  "type": "font_picker",
  "id": "heading_font",
  "label": "Heading font",
  "default": "helvetica_n4"
}

Output: object (font object) Access properties:

{{ settings.heading_font | font_property: 'family' }}
{{ settings.heading_font | font_property: 'fallback_families' }}
{{ settings.heading_font | font_property: 'weight' }}
{{ settings.heading_font | font_property: 'style' }}

Generate CSS:

{{ settings.heading_font | font_face }}
{{ settings.heading_font | font_face: font_display: 'swap' }}

Modify font:

{% assign bold_font = settings.heading_font | font_modify: 'weight', 'bold' %}

Media Settings

image_picker

Image upload/select.

{
  "type": "image_picker",
  "id": "image",
  "label": "Image"
}

Output: object (image object) or nil Properties:

Property	Type	Description
`.src`	string	Image URL
`.alt`	string	Alt text
`.width`	number	Original width
`.height`	number	Original height
`.aspect_ratio`	number	Width / height

{% if section.settings.image %}
  <img 
    src="{{ section.settings.image | img_url: '800x' }}"
    alt="{{ section.settings.image.alt }}"
    width="{{ section.settings.image.width }}"
    height="{{ section.settings.image.height }}"
    loading="lazy"
  >
{% endif %}

video

Hosted video file.

{
  "type": "video",
  "id": "video",
  "label": "Video"
}

Output: object (video object) or nil

{% if section.settings.video %}
  {{ section.settings.video | video_tag: autoplay: true, loop: true, muted: true }}
{% endif %}

video_url

YouTube/Vimeo URL input.

{
  "type": "video_url",
  "id": "video_url",
  "label": "Video URL",
  "accept": ["youtube", "vimeo"],
  "placeholder": "https://www.youtube.com/watch?v=..."
}

Properties:

Property	Type	Description
`accept`	array	Allowed providers

Output: string (URL) or nil

{% if section.settings.video_url %}
  {{ section.settings.video_url | external_video_tag }}
{% endif %}

Resource Settings

product

Single product selector.

{
  "type": "product",
  "id": "featured_product",
  "label": "Featured product"
}

Output: object (full product object) or nil

{% assign product = section.settings.featured_product %}
{% if product %}
  {% render 'product-card', product: product %}
{% endif %}

product_list

Multiple products selector.

{
  "type": "product_list",
  "id": "products",
  "label": "Products",
  "limit": 12
}

Properties:

Property	Type	Description
`limit`	number	Maximum products

Output: array of product objects

{% for product in section.settings.products %}
  {% render 'product-card', product: product %}
{% endfor %}

collection

Single collection selector.

{
  "type": "collection",
  "id": "collection",
  "label": "Collection"
}

Output: object (collection object) or nil

{% assign collection = section.settings.collection %}
{% for product in collection.products limit: 4 %}
  {{ product.title }}
{% endfor %}

collection_list

Multiple collections selector.

{
  "type": "collection_list",
  "id": "collections",
  "label": "Collections",
  "limit": 6
}

Output: array of collection objects

blog

Blog selector.

{
  "type": "blog",
  "id": "blog",
  "label": "Blog"
}

Output: object (blog object) or nil

article

Article selector.

{
  "type": "article",
  "id": "article",
  "label": "Featured article"
}

Output: object (article object) or nil

page

Page selector.

{
  "type": "page",
  "id": "page",
  "label": "Page"
}

Output: object (page object) or nil

link_list

Navigation menu selector.

{
  "type": "link_list",
  "id": "menu",
  "label": "Menu",
  "default": "main-menu"
}

Output: object (linklist object) or nil

{% for link in section.settings.menu.links %}
  <a href="{{ link.url }}">{{ link.title }}</a>
{% endfor %}

Link Settings

url

URL input with link picker.

{
  "type": "url",
  "id": "button_link",
  "label": "Button link",
  "default": "/collections/all"
}

Output: string (URL) or nil The link picker allows selecting:

Products
Collections
Pages
Blogs
Articles
Custom URLs

Informational Settings

Section divider with heading.

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

No output. Used only for organizing the settings panel.

paragraph

Read-only help text.

{
  "type": "paragraph",
  "content": "Use the settings below to customize the appearance of this section."
}

No output. Used only for displaying information in the settings panel.

Best Practices

Grouping with Headers

{
  "settings": [
    {
      "type": "header",
      "content": "Content"
    },
    { "type": "text", "id": "heading", "label": "Heading" },
    { "type": "richtext", "id": "text", "label": "Text" },
    
    {
      "type": "header",
      "content": "Layout"
    },
    { "type": "range", "id": "padding", "label": "Padding", "min": 0, "max": 100, "step": 4, "unit": "px", "default": 40 },
    
    {
      "type": "header",
      "content": "Colors"
    },
    { "type": "color_scheme", "id": "color_scheme", "label": "Color scheme", "default": "scheme-1" }
  ]
}

Providing Helpful Info

{
  "type": "range",
  "id": "speed",
  "label": "Animation speed",
  "min": 0.5,
  "max": 3,
  "step": 0.1,
  "unit": "s",
  "default": 1,
  "info": "Lower values are faster. Set to 0 to disable animations."
}

Translation Keys

Use t: prefix for all user-facing strings:

{
  "type": "text",
  "id": "heading",
  "label": "t:sections.hero.settings.heading.label",
  "default": "t:sections.hero.settings.heading.default",
  "info": "t:sections.hero.settings.heading.info"
}

Aqua Basics

Theme Schema

Documentation Index

​Input Settings Reference

​Quick Reference

​Text Settings

​text

​textarea

​richtext

​inline_richtext

​html

​Selection Settings

​select

​radio

​checkbox

​Numeric Settings

​range

​number

​Color Settings

​color

​color_background

​color_scheme

​Font Settings

​font_picker

​Media Settings

​image_picker

​video

​video_url

​Resource Settings

​product

​product_list

​collection

​collection_list

​blog

​article

​page

​link_list

​Link Settings

​url

​Informational Settings

​header

​paragraph

​Best Practices

​Grouping with Headers

​Providing Helpful Info

​Translation Keys

Input Settings Reference

Quick Reference

Text Settings

text

textarea

richtext

inline_richtext

html

Selection Settings

select

radio

checkbox

Numeric Settings

range

number

Color Settings

color

color_background

color_scheme

Font Settings

font_picker

Media Settings

image_picker

video

video_url

Resource Settings

product

product_list

collection

collection_list

blog

article

page

link_list

Link Settings

url

Informational Settings

header

paragraph

Best Practices

Grouping with Headers

Providing Helpful Info

Translation Keys