---
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)
* [color](#color)
* [html](#html)
* [image\_picker](#image_picker)
* [link\_list](#link_list)
* [liquid](#liquid)
* [page](#page)
* [product](#product)
* [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.

### `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.

### `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.

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