Input settings ​

Input settings open up theme customization for sellers, these can be further split into two subcategories:

• Basic input settings.
• Advanced input settings.

This separation takes into account whether the value from the setting is transformed before it reaches the liquid template, or if it is provided as is.

Properties ​

The following properties are shared across all input settings. Some setting types may not follow this rule, in which case it will be documented in that type's section.

Basic input settings ​

These are the available basic settng types:

• checkbox
• number
• radio
• range
• select
• text
• textarea

text ​

This type outputs a text input. It may contain an additional placeholder attribute, which is to be displayed when the input's value is empty. The value returned is a string, if no value is specified it defaults to blank.

{
    "type": "text",
    "id": "product_extra_description",
    "label": "Description",
    "default": "Some product description"
}

number ​

This type outputs a number input. It may contain an additional placeholder attribute, which is to be displayed when the input's value is empty. The value returned is a number, if no value is specified it defaults to blank.

{
    "type": "number",
    "id": "number_of_rows",
    "label": "Number of rows",
    "default": 7
}

radio ​

A radio input setting has a required options attribute that accepts an array of value and label definitions. The value returned is a string, if no value is specified it defaults to the first option.

{
    "type": "radio",
    "id": "text_font_family",
    "label": "Font family",
    "options": [
        {
            "value": "monospace",
            "label": "Monospaced"
        },
        {
            "value": "serif",
            "label": "Serif"
        }
    ],
    "default": "monospace"
}

select ​

A select input setting has a required options attribute that accepts an array of value and label definitions. The value returned is a string, if no value is specified it defaults to the first option.

{
    "type": "select",
    "id": "text_font_family",
    "label": "Font family",
    "options": [
        {
            "value": "monospace",
            "label": "Monospaced"
        },
        {
            "value": "serif",
            "label": "Serif"
        }
    ],
    "default": "monospace"
}

checkbox ​

This type outputs a checkbox input, it is best fit to toggle theme features on or off. The value returned is a boolean, if no value is specified it defaults to false.

{
    "type": "checkbox",
    "id": "show_product",
    "label": "Show product",
    "default": true
}

textarea ​

This type outputs a text area. It may contain an additional placeholder attribute, which is to be displayed when the input's value is empty. The value returned is a string, if no value is specified it defaults to blank.

{
    "type": "textarea",
    "id": "announcement_bar_text",
    "label": "Text",
    "default": "Welcome to the store."
}

range ​

This type outputs a range slider, which can be customized using the properties listed below. Note that all properties are required except for the unit.

{
    "type": "range",
    "id": "font_size",
    "min": 12,
    "max": 24,
    "step": 1,
    "unit": "px",
    "label": "Font size",
    "default": 16
}

Advanced input settings ​

These are the available advanced settng types:

• category
• color
• color_background
• html
• image_picker
• liquid
• page
• product
• richtext
• url
• video_url

category ​

A setting of type category generates a product category picker, allowing you to capture a category object from the seller. The category setting type does not accept a default value.

{
    "type": "category",
    "id": "category",
    "label": "Category"
}

Accessing the category setting will return one of the following:

• A category object.
• A blank value if no valid category is selected.

color ​

A setting of type color generates a simple color picker, allowing for the capture of one color from the seller.

{
    "type": "color",
    "id": "color",
    "label": "Color",
    "default": "#ff7420"
}

Accessing the color setting will return one of the following:

• A color object.
• A blank value if no color is selected.

html ​

A setting of type html generates a text area allowing for the capture of raw HTML code. It may contain an additional placeholder attribute.

{
    "type": "html",
    "id": "html",
    "label": "Custom HTML"
}

image_picker ​

A setting of type image picker generates an image selector field, allowing the seller to select one of their store images or upload a new one. This setting does not support the default attribute.

{
    "type": "image_picker",
    "id": "banner_image",
    "label": "Banner image"
}

Accessing the color setting will return one of the following:

• An image object.
• A blank value if no image is selected.

liquid ​

A setting of type liquid generates a text area allowing for the capture of raw Liquid code. Keep in mind that the captured liquid markup is limited and does not have access to every liquid object.

{
    "type": "liquid",
    "id": "custom_liquid",
    "label": "Custom Liquid markup"
}

page ​

A setting of type page generates a product page picker, allowing you to capture a page object from the seller. The page setting type does not accept a default value.

{
    "type": "page",
    "id": "page_to_display",
    "label": "Page to display"
}

Accessing the category setting will return one of the following:

• A page object.
• A blank value if no valid page is selected.

product ​

A setting of type product generates a product product picker, allowing you to capture a product object from the seller. The product setting type does not accept a default value.

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

Accessing the product setting will return one of the following:

• A product object.
• A blank value if no valid product is selected.

richtext ​

A setting of type richtext generates a rich text editor, allowing for the capture of limited HTML markup.

{
    "type": "richtext",
    "id": "welcome_message",
    "label": "Welcome message"
}

url ​

A setting of type url generates a text field to capture an external or internal URL.

{
    "type": "url",
    "id": "button_link",
    "label": "Button link"
}

video_url ​

A setting of type video_url generates a URL entry field, allowing for the capture of a YouTube or Vimeo video link. The video_url setting accepts two additional attributes:

• An optional placeholder attribute, to specify what to show when no selection is made.
• A required accept attribute which takes an array of allowed providers. Current supported providers are vimeo and youtube.

{
    "type": "video_url",
    "id": "video_url",
    "label": "Video",
    "accept": ["youtube", "vimeo"]
}