Input settings

Input settings can hold a value and are configurable by merchants.

Input settings are generally composed of standard attributes, and there are two categories:

Standard attributes

The following are standard attributes across input settings. However, depending on the input type, there might be extra attributes or some might not apply:

Attribute Description Required
type The setting type, which can be any of the basic or specialized input setting types. Yes
id The setting ID, which is used to access the setting value. Yes
label The setting label, which will show in the theme editor. Yes
default The default value for the setting. No
info An option for informational text about the setting. No

Basic input settings

The following are the basic input setting types:

checkbox

A setting of type checkbox outputs a checkbox field. These fields can be used for toggling features on and off, such as whether to show an announcement bar.

For example, the following setting generates the following output:

Output

When accessing the value of a checkbox type setting, data is returned as a Boolean.

number

A setting of type number outputs a single number field. In addition to the standard attributes of an input setting, number type settings have the following attribute:

Attribute Description Required
placeholder A placeholder value for the input No

You can use these fields to capture a varying numerical value, such as the number of products to show per page on a collection page.

For example, the following setting generates the following output:

Output

When accessing the value of a number type setting, data is returned as one of the following:

radio

A setting of type radio outputs a radio option field. In addition to the standard attributes of an input setting, radio type settings have a required options attribute that accepts an array of value and label definitions.

You can use these fields to capture a multi-option selection, such as the alignment of a header logo.

For example, the following setting generates the following output:

Output

When accessing the value of a radio type setting, data is returned as a String.

range

A setting of type range outputs a range slider field. In addition to the standard attributes of an input setting, range type settings have the following attributes:

Attribute Description Required
min The minimum value of the input Yes
max The maximum value of the input Yes
step The increment size between steps of the slider Yes
unit The unit for the input. For example, you can set px for a font-size slider. No

You can use these fields to capture a varying numerical value, such as font size.

For example, the following setting generates the following output:

Output

When accessing the value of a range type setting, data is returned as a Number.

select

A setting of type select outputs a drop-down selector field. In addition to the standard attributes of an input setting, select type settings have the following attributes:

Attribute Description Required
options Takes an array of value/label definitions for each option in the drop-down. Yes
group An optional attribute you can add to each option to create option groups in the drop-down. No

You can use these fields to capture a multi-option selection, such as the vertical alignment of slideshow text.

For example, the following setting generates the following output:

Output

When accessing the value of a select type setting, data is returned as a String.

text

A setting of type text outputs a single-line text field. In addition to the standard attributes of an input setting, text type settings have the following attribute:

Attribute Description Required
placeholder A placeholder value for the input No

You can use these fields to capture short strings, such as titles.

For example, the following setting generates the following output

Output

When accessing the value of a text type setting, data is returned as one of the following:

textarea

A setting of type textarea outputs a multi-line text field. In addition to the standard attributes of an input setting, textarea type settings have the following attribute:

Attribute Description Required
placeholder A placeholder value for the input. No

You can use these fields to capture larger blocks of text, such as messages.

For example, the following setting generates the following output:

Output

When accessing the value of a textarea type setting, data is returned as one of the following:

Specialized input settings

The following are the specialized input setting types:

article

A setting of type article outputs an article picker field that's automatically populated with the available articles for the store. You can use these fields to capture an article selection, such as the article to feature on the homepage.

For example, the following setting generates the following output:

Output

When accessing the value of an article type setting, data is returned as one of the following:

  • An article object.
  • blank if no selection has been made, the selection isn't visible, or the selection no longer exists.

blog

A setting of type blog outputs a blog picker field that's automatically populated with the available blogs for the store. You can use these fields to capture a blog selection, such as the blog to feature in the sidebar.

For example, the following setting generates the following output:

Output

When accessing the value of a blog type setting, data is returned as one of the following:

  • A blog object.
  • blank, if either no selection has been made or the selection no longer exists.

collection

A setting of type collection outputs a collection picker field that's automatically populated with the available collections for the store. You can use these fields to capture a collection selection, such as a collection for featuring products on the homepage.

For example, the following setting generates the following output:

Output

When accessing the value of a collection type setting, data is returned as one of the following:

  • A collection object.
  • blank, if no selection has been made, the selection isn't visible, or the selection no longer exists.

color

A setting of type color outputs a color picker field. You can use these fields to capture a color selection for various theme elements, such as the body text color.

For example, the following setting generates the following output:

Output

When accessing the value of a color type setting, data is returned as one of the following:

color_background

A setting of type color_background outputs a text field for entering CSS background properties. You can use these fields to capture background settings for various theme elements, such as the store background.

For example, the following setting generates the following output:

Output

When accessing the value of a color_background type setting, data is returned as one of the following:

  • A String.
  • nil, if nothing has been entered.

font_picker

A setting of type font_picker outputs a font picker field that's automatically populated with fonts from the Shopify font library. This library includes web-safe fonts, a selection of Google Fonts, and fonts licensed by Monotype.

You can use these fields to capture a font selection for various theme elements, such as the base heading font.

For example, the following setting generates the following output:

Output

When accessing the value of a font_picker type setting, data is returned as a font object.

html

A setting of type html outputs a multi-line text field that accepts HTML markup. In addition to the standard attributes of an input setting, html type settings have the following attribute:

Attribute Description Required
placeholder A placeholder value for the input No

You can use these fields to capture custom blocks of HTML content, such as a video embed.

For example, the following setting generates the following output:

Output

The following HTML tags will be automatically removed:

  • <html>
  • <head>
  • <body>

When accessing the value of an html type setting, data is returned as one of the following:

  • A String that contains the entered content.
  • An EmptyDrop, if nothing has been entered.

image_picker

A setting of type image_picker outputs an image picker field that's automatically populated with the available images from the Files section of Shopify admin, and has the option to upload new images. You can use these fields to capture an image selection, such as logos, a favicons, and slideshow images.

For example, the following setting generates the following output:

Output

When accessing the value of an image_picker type setting, data is returned as one of the following:

  • An image object.
  • nil, if either no selection has been made or the selection no longer exists.

A setting of type link_list outputs a menu picker field that's automatically populated with the available menus for the store. You can use these fields to capture a menu selection, such as the menu to use for footer links.

For example, the following setting generates the following output:

Output

When accessing the value of a link_list type setting, data is returned as one of the following:

  • A linklist object.
  • blank, if either no selection has been made or the selection no longer exists.

liquid

A setting of type liquid outputs a multi-line text field that accepts HTML and limited Liquid markup. You can use these fields to capture custom blocks of HTML and Liquid content, such as a product-specific message. Merchants can also use a liquid setting to add the code needed to integrate certain types of apps into your theme.

For example, the following setting generates the following output:

Output

When accessing the value of a liquid type setting, data is returned as one of the following:

  • A String that contains the entered content.
  • An EmptyDrop, if nothing has been entered.

Limitations

Settings of type liquid don't have access to the following liquid objects/tags:

However, liquid settings can access the following:

If your content includes non-existent, or empty, Liquid tags, then they will be rendered as empty strings. For example, the following setting generates the following output:

Output

page

A setting of type page outputs a page picker field that's automatically populated with the available pages for the store. You can use these fields to capture a page selection, such as the page to feature content for in a size-chart display.

For example, the following setting generates the following output:

Output

When accessing the value of a page type setting, data is returned as one of the following:

  • A page object.
  • blank, if no selection has been made, the selection isn't visible, or the selection no longer exists.

product

A setting of type product outputs a product picker field that's automatically populated with the available products for the store. You can use these fields to capture a product selection, such as the product to feature on the homepage.

For example, the following setting generates the following output:

Output

When accessing the value of a product type setting, data is returned as one of the following:

  • A product object.
  • blank if no selection has been made, the selection isn't visible, or the selection no longer exists.

richtext

A setting of type richtext outputs a multi-line text field with the following basic formatting options:

  • Bold
  • Italic
  • Underline
  • Link
  • Paragraph

You can use these fields to capture formatted text content, such as introductory brand content on the homepage.

For example, the following setting generates the following output:

Output

When accessing the value of a richtext type setting, data is returned as one of the following:

  • A String that contains the entered content.
  • An EmptyDrop, if nothing has been entered.

default

The default attribute isn't required. However, if it's used, then the content must be wrapped in <p> tags.

The following HTML tags are also supported inside the parent <p> tag:

  • <p>
  • <br>
  • <strong>
  • <b>
  • <em>
  • <i>
  • <u>
  • <span>
  • <a>

url

A setting of type url outputs a URL entry field where you can manually enter external URLs and relative paths. It also has a picker that's automatically populated with the following available resources for the shop:

  • Articles
  • Blogs
  • Collections
  • Pages
  • Products

You can use these fields to capture a URL selection, such as the URL to use for a slideshow button link.

For example, the following setting generates the following output:

Output

When accessing the value of a url type setting, data is returned as one of the following:

  • A String that contains the selected URL.
  • nil, if nothing has been entered.

video_url

A setting of type video_url outputs a URL entry field. In addition to the standard attributes of an input setting, video_url type settings have the following attributes:

Attribute Description Required
accept Takes an array of accepted video providers. Valid values are youtube, vimeo, or both. Yes
placeholder A placeholder value for the input. No

These fields can be used to capture a video URL from YouTube and/or Vimeo, such as the URL for a static video to show in the product description.

For example, the following setting generates the following output:

Output

When accessing the value of a video_url type setting, data is returned as one of the following:

  • A String that contains the entered URL.
  • nil, if nothing has been entered.

Additionally, there's access to the id and type (YouTube or Vimeo) of the video.

For example, assuming you're using this video with the above setting, the following Liquid generates the following output:

Output

You can add links to the info settings attribute by enclosing the link text in brackets and then following it immediately with the URL in parentheses.

For example, the following setting generates the following output:

Output