.dev
Partner Dashboard

Input settings ​

Last updated View as Markdown

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"
}

The seller can also pick the All products option. The value is then all, and the setting returns the collection that has every product of the store, the same object as collections['all'].

A template can set the value to all. For example, this homepage section lists the newest products of a new store:

json
{
  "type": "products-by-collection",
  "settings": {
    "collection": "all"
  }
}

Accessing the collection setting will return one of the following:

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

collection_list ​

A setting of type collection_list generates a picker for several collections. The seller adds collections one by one, and the order they pick is kept. The collection_list setting type does not accept a default value.

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

limit is the most collections the seller can pick, from 1 to 50. The default is 50. The All products option can be picked too.

Accessing the collection_list setting returns an array of category objects, in the order the seller picked them. A collection that was deleted or hidden since is left out. If nothing is picked, the array is empty.

liquid
{% for collection in section.settings.collections %}
  <a href="{{ collection.url }}">{{ collection.name }}</a>
{% endfor %}

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.

The value or the default can be a color of the theme's palette, written as a Liquid output tag. When the seller changes that palette color, the setting changes with it.

json
{
    "type": "color",
    "id": "button_border",
    "label": "Button border",
    "default": "{{ settings.colors.accent }}"
}

color_background ​

With a setting of type color_background, the seller picks a linear or a radial gradient, its angle and its color stops.

json
{
    "type": "color_background",
    "id": "background_gradient",
    "label": "Background gradient"
}

You get one of the following from the color_background setting:

  • The CSS background value as a string, for example linear-gradient(135deg, #e1116f 0%, #7d52f4 100%).
  • A blank value if no gradient is selected.
liquid
{% if section.settings.background_gradient != blank %}
  <div style="background: {{ section.settings.background_gradient }}">
{% endif %}

Like color, the value can be a palette color such as {{ settings.colors.accent }}. You then get that color as a hex string.

color_palette ​

Use a setting of type color_palette to define a set of named colors for the theme's color and color_background settings. A theme can have only one, in settings_schema.json. It takes only id and default.

json
{
    "type": "color_palette",
    "id": "colors",
    "default": {
        "background": "#FFFFFF",
        "foreground": "#121212",
        "accent": "#E11D48"
    }
}

The default has 2 to 20 colors. Keys start with a letter and contain letters, digits and underscores. Values are hex colors without alpha, for example #FFF or #FF4416.

Each palette color is a color object. When you loop over the palette, you get each color in key order, without the keys.

liquid
:root {
  --background: {{ settings.colors.background }};
  --accent: {{ settings.colors.accent }};
}

{% for color in settings.colors %}
  {{ color.hex }}
{% endfor %}

To use a palette color in a color or color_background setting, write a Liquid output tag with the palette key, for example {{ settings.colors.accent }}. When the seller changes that palette color, every setting that uses it changes too. If the key does not exist, you get blank.

When the seller deletes a palette color, they pick another color to replace it. The deleted key is kept as a reference to the replacement, and the settings that used the deleted color get the replacement.

color_scheme ​

With a setting of type color_scheme, the seller picks one of the theme's color schemes.

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

You get a color_scheme object from the color_scheme setting. If the scheme ID no longer exists, you get the first scheme of the theme. When you output the setting directly, you get the scheme ID.

liquid
<section class="color-{{ section.settings.color_scheme }}">

color_scheme_group ​

Use a setting of type color_scheme_group to define the theme's color schemes. A theme can have only one, in settings_schema.json. The seller adds, edits and deletes schemes in the theme editor.

json
{
    "type": "color_scheme_group",
    "id": "color_schemes",
    "definition": [
        { "type": "color", "id": "background", "label": "Background", "default": "#FFFFFF" },
        { "type": "color_background", "id": "background_gradient", "label": "Background gradient" },
        { "type": "color", "id": "text", "label": "Text", "default": "#121212" },
        { "type": "color", "id": "button", "label": "Button", "default": "#E11D48" },
        { "type": "color", "id": "button_label", "label": "Button label", "default": "#FFFFFF" }
    ],
    "role": {
        "background": { "solid": "background", "gradient": "background_gradient" },
        "text": "text",
        "primary_button": "button",
        "on_primary_button": "button_label"
    }
}
PropertyRequiredDescription
definitionYesThe settings of each scheme. Use color, color_background and header settings.
roleNoMaps roles to setting IDs. The scheme previews in the theme editor are drawn from it. The roles are background, text, primary_button, on_primary_button, secondary_button and secondary_button_border.

The schemes are stored in settings_data.json under the setting ID. If a scheme leaves out a setting, the default is used.

json
"color_schemes": {
    "scheme-1": { "settings": { "background": "#FFFFFF", "text": "#121212" } },
    "scheme-2": { "settings": { "background": "#0F172A", "text": "#F8FAFC" } }
}

You get the schemes from settings.color_schemes as color_scheme objects. Loop over it to get each scheme in order, or use an ID to get one scheme.

liquid
<style>
  {% for scheme in settings.color_schemes %}
    .color-{{ scheme.id }} {
      --background: {{ scheme.settings.background }};
      --text: {{ scheme.settings.text }};
      --gradient: {{ scheme.settings.background_gradient | default: scheme.settings.background }};
    }
  {% endfor %}
</style>

{{ settings.color_schemes['scheme-2'].settings.text }}

font_picker ​

A setting of type font_picker generates a font picker with every Google font and the system fonts. The seller picks a family and a weight and style. The font_picker setting type requires a default.

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

The value is the family name in lowercase with _ instead of spaces, then _n for normal or _i for italic, then the weight divided by 100. For example poppins_n4 is Poppins regular, and playfair_display_i7 is Playfair Display bold italic. The system fonts are sans-serif, serif and monospace, for example sans-serif_n4.

Accessing the font_picker setting returns a font object. Load it with the font_face filter.

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.

product_list ​

A setting of type product_list generates a picker for several products. The seller adds products one by one, and the order they pick is kept. The product_list setting type does not accept a default value.

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

limit is the most products the seller can pick, from 1 to 50. The default is 50.

Accessing the product_list setting returns an array of product objects, in the order the seller picked them. A product that was deleted since is left out. If nothing is picked, the array is empty.

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

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"]
}