.dev

Appearance

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.

PropertyRequiredDescription
typeYesThe input setting's type.
idYesAn identifier with which the setting can be referenced from the template.
labelYesThe settings name which is to be displayed as a label on the theme editor.
defaultNoA default value for the setting if none is provided by the seller.
infoNoAn arbitrary value describing the setting for the seller.

Basic input settings ​

These are the available basic settng types:

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.

json
{
    "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.

json
{
    "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.

json
{
    "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.

json
{
    "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.

json
{
    "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.

json
{
    "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.

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

text_alignment ​

This type outputs a control with three alignment options. The value returned is one of left, center or right. If no default is given, it defaults to left.

json
{
    "type": "text_alignment",
    "id": "heading_alignment",
    "label": "Heading alignment",
    "default": "center"
}

inline_richtext ​

This type outputs a single-line rich text editor with bold, italic and link formatting. The value returned is a string of HTML without a wrapping paragraph, so it can be used inside a heading or a button. Only the a, b, strong, i and em tags are allowed.

json
{
    "type": "inline_richtext",
    "id": "heading",
    "label": "Heading",
    "default": "Free shipping on <strong>all</strong> orders"
}

Advanced input settings ​

These are the available advanced settng types:

collection ​

A setting of type collection generates a product category picker, allowing you to capture a category object from the seller. The collection setting type does not accept a default value. The older category type name still works, but it is deprecated.

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

Accessing the collection 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.

json
{
    "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.

json
{
    "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.

json
{
    "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.

A setting of type link_list generates a menu picker, allowing you to capture one of the store menus from the seller. The value is the menu handle, so the default can name a menu that every store has, such as main-menu.

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

Accessing the link_list setting will return one of the following:

  • A link_list object.
  • A blank value if no menu with that handle exists.

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.

json
{
    "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.

json
{
    "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.

json
{
    "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.

json
{
    "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.

json
{
    "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.
json
{
    "type": "video_url",
    "id": "video_url",
    "label": "Video",
    "accept": ["youtube", "vimeo"]
}

© 2022-2026 YouCan