---
url: https://docs.youcan.shop/themes/settings/input_settings.md
---
# 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.

| Property  | Required | Description                                                                |
| --------- | -------- | -------------------------------------------------------------------------- |
| `type`    | Yes      | The input setting's type.                                                  |
| `id`      | Yes      | An identifier with which the setting can be referenced from the template.  |
| `label`   | Yes      | The settings name which is to be displayed as a label on the theme editor. |
| `default` | No       | A default value for the setting if none is provided by the seller.         |
| `info`    | No       | An arbitrary value describing the setting for the seller.                  |

## Basic input settings

These are the available basic settng types:

* [checkbox](#checkbox)
* [inline\_richtext](#inline_richtext)
* [number](#number)
* [radio](#radio)
* [range](#range)
* [select](#select)
* [text](#text)
* [text\_alignment](#text_alignment)
* [textarea](#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`.

```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](#collection)
* [collection\_list](#collection_list)
* [color](#color)
* [color\_background](#color_background)
* [color\_palette](#color_palette)
* [color\_scheme](#color_scheme)
* [color\_scheme\_group](#color_scheme_group)
* [font\_picker](#font_picker)
* [html](#html)
* [image\_picker](#image_picker)
* [link\_list](#link_list)
* [liquid](#liquid)
* [page](#page)
* [product](#product)
* [product\_list](#product_list)
* [richtext](#richtext)
* [url](#url)
* [video\_url](#video_url)

### `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](/themes/objects/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](/themes/objects/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](/themes/objects/color) object.
* A `blank` value if no color is selected.

The value or the `default` can be a color of the theme's [palette](#color_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_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](/themes/config/settings_schema). 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](/themes/objects/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](#color_scheme_group).

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

You get a [color\_scheme](/themes/objects/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](/themes/config/settings_schema). 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"
    }
}
```

| Property | Required | Description |
| -------- | -------- | ----------- |
| `definition` | Yes | The settings of each scheme. Use `color`, `color_background` and `header` settings. |
| `role` | No | Maps 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](/themes/config/settings_data) 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](/themes/objects/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](/themes/objects/font) object. Load it with the [font\_face](/themes/filters/fonts/fontFace) 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](/themes/objects/image) object.
* A `blank` value if no image is selected.

### `link_list`

A setting of type link\_list generates a menu picker, allowing you to capture one of the store [menus](https://seller-area.youcan.shop/admin/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](/themes/objects/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](/themes/objects/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](/themes/objects/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](/themes/objects/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"]
}
```