Input settings

AskCopy MD

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

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

• Basic input settings
• Specialized input settings

To learn how to access the values of these settings for use in your theme, refer to the settings overview.

---

Anchor to Standard attributesStandard 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:

---

Anchor to Basic input settingsBasic input settings

The following are the basic input setting types:

• checkbox
• number
• radio
• range
• select
• text
• textarea

---

Anchor to [object Object]checkbox

A setting of type checkbox outputs a checkbox field. This setting type 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:

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

---

Anchor to [object Object]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:

You can use this setting type 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:

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

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

---

Anchor to [object Object]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 this setting type to capture a multi-option selection, such as the alignment of a header logo.

For example, the following setting generates the following output:

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

---

Anchor to [object Object]range

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

You can use this setting type to capture a varying numerical value, such as font size.

You can update the range value using the provided slider, or by typing a value into the input field:

• If you enter a value that doesn't respect the step definition, then the value rounds to the closest step.
• If you enter a value outside of the given min and max, then the value reverts to the min or max value accordingly.

For example, the following setting generates the following output:

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

---

Anchor to [object Object]select

A setting of type select outputs different selector fields, depending on certain criteria. In addition to the standard attributes of an input setting, select type settings have the following attributes:

Anchor to Selector fieldsSelector fields

The following criteria render selector fields as either a DropDown or a SegmentedControl:

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

For example, the following setting generates the following output:

However, if your setting matches the criteria for a drop-down field (DropDown) because it has more than five options, then the following output is generated:

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

---

Anchor to [object Object]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:

You can use this setting type to capture short strings, such as titles.

For example, the following setting generates the following output:

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

• A string.
• An empty object, if nothing has been entered.

---

Anchor to [object Object]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:

You can use this setting type to capture larger blocks of text, such as messages.

For example, the following setting generates the following output:

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

• A string.
• An empty object, if nothing has been entered.

---

Anchor to Specialized input settingsSpecialized input settings

The following are the specialized input setting types:

• article
• article_list
• blog
• collection
• collection_list
• color
• color_background
• color_palette
• font_picker
• html
• image_picker
• inline_richtext
• link_list
• liquid
• metaobject
• metaobject_list
• page
• product
• product_list
• richtext
• text_alignment
• url
• video
• video_url

---

Anchor to [object Object]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 this setting type to capture an article selection, such as the article to feature on the homepage.

For example, the following setting generates the following output:

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

• An article object.

To ensure backwards compatibility with legacy resource-based settings, outputting the setting directly will return the object's handle.

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

---

Anchor to [object Object]article_list

A setting of type article_list outputs an article picker field that's automatically populated with the available blog articles for the store. You can use this setting type to capture multiple articles, such as a group of articles to feature on the homepage.

In addition to the standard attributes of an input setting, article_list type settings have the following attributes:

When accessing the value of an article_list type setting, data is returned in one of the following formats:

• An array of article objects

The array supports pagination using the paginate tag. You can also append .count to the setting key to return the number of articles in the array.

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

---

Anchor to [object Object]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 this setting type to capture a blog selection, such as the blog to feature in the sidebar.

For example, the following setting generates the following output:

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

• A blog object.

To ensure backwards compatibility with legacy resource-based settings, outputting the setting directly will return the object's handle.

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

---

Anchor to [object Object]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 this setting type to capture a collection selection, such as a collection for featuring products on the homepage.

For example, the following setting generates the following output:

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

• A collection object.

To ensure backwards compatibility with legacy resource-based settings, outputting the setting directly will return the object's handle.

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

---

Anchor to [object Object]collection_list

A setting of type collection_list outputs a collection picker field that's automatically populated with the available collections for the store. You can use this setting type to capture multiple collections, such as a group of collections to feature on the homepage.

In addition to the standard attributes of an input setting, collection_list type settings have the following attributes:

When accessing the value of a collection_list type setting, data is returned in one of the following formats:

• An array of collection objects

The array supports pagination using the paginate tag. You can also append .count to the setting key to return the number of collections in the array.

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

---

Anchor to [object Object]color

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

You can use this setting type to capture a color selection for various theme elements, such as the body text color. The placeholder attribute displays custom text when no color is set, without affecting the stored value.

For example, the following setting generates the following output:

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

• A color object.
• blank, if no selection has been made.

If default is omitted, merchants see a Clear option in the editor. Clearing stores "" in settings_data.json and returns blank in Liquid. An unset color is visually distinct from transparent (#00000000).

If your theme defines a color_palette, you can use a palette color as the default value:

---

Anchor to [object Object]color_background

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

For example, the following setting generates the following output:

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

• A string.
• An empty string, if nothing has been entered.

If your theme defines a color_palette, you can use palette colors as the default value. Palette references can be embedded inside gradient strings:

---

Anchor to [object Object]color_palette

A setting of type color_palette defines a set of named colors available across your theme's color and color_background settings. Merchants see these colors in a grid in the theme editor and can pick from them when adjusting any color setting.

You can add only one color_palette per theme, and it must be in settings_schema.json. The default object defines the theme's starting palette. Any changes a merchant makes in the theme editor are stored in settings_data.json and take precedence over the defaults.

Unlike most input settings, color_palette supports only the id standard attribute, which is required. The label, info, and visible_if attributes aren't supported. It has the following additional attribute:

A palette supports between 2 and 20 colors. Colors are returned in the order they appear in the JSON.

For example, the following setting generates the following output:

When accessing the value of a color_palette type setting, you access individual palette colors through settings.<id>, where <id> matches the id you defined in the schema. Each color is returned as a color object with full access to color properties and filters.

Iterating over the palette yields each color as a color object in JSON key order. Keys aren't available during iteration, only the color values:

Anchor to Cross-setting referencesCross-setting references

You can use a palette color as the default value of a color or color_background setting. The value must be a Liquid output tag that references a palette key, for example {{ settings.colors.primary }}. Only color_palette access paths are supported as dynamic defaults. See the color and color_background sections for examples.

Anchor to Theme updatesTheme updates

When a theme update adds new keys to the palette default, those keys appear automatically in the merchant's palette. Merchant-customized values are preserved and take precedence over new defaults.

Anchor to Deleting palette colorsDeleting palette colors

When a merchant deletes a palette color in the theme editor, Shopify asks them to choose a replacement. The deleted color's value is stored as a reference to the replacement, for example {{ settings.colors.accent }}. This keeps all existing references intact without updating every template that uses the deleted color.

---

Anchor to [object Object]color_scheme

The color_scheme and color_scheme_group setting types have been replaced by color_palette. For the full reference, including schema examples, Liquid access, and role definitions, see deprecated settings.

---

Anchor to [object Object]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 system fonts and a selection of Google Fonts.

You can use this setting type to capture a font selection for various theme elements, such as the base heading font.

For example, the following setting generates the following output:

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

---

Anchor to [object 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:

You can use this setting type to capture custom blocks of HTML content, such as a video embed.

For example, the following setting generates the following output:

The following HTML tags will be automatically removed:

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

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

• A string that contains the entered content.
• An empty object, if nothing has been entered.

---

Anchor to [object Object]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. Merchants also have an opportunity to enter alt text and select a focal point for their image.

You can use this setting type to capture an image selection, such as logos, favicons, and slideshow images.

For example, the following setting generates the following output:

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

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

Anchor to Image focal pointsImage focal points

Images selected using an image_picker setting support focal points. A focal point is a position in an image that the merchant wants to remain in view as the image is cropped and adjusted by the theme. Focal points can be set in the theme editor image_picker setting, or from the Files page.

To make sure that your theme respects the focal point of the image, do the following:

• Render your images using the image_tag filter.
• Consider positioning images within containers using object-fit: cover.

Using image_tag, if a focal point was provided, then an object-position style is added to the image tag, with the value set to the focal point.

If you need to override the object-position style for a specific use case, then pass a style: object-position: inherit; property to the image_tag filter.

---

Anchor to [object Object]inline_richtext

A setting of type inline_richtext outputs HTML markup that isn't wrapped in paragraph tags (<p>). The setting includes the following basic formatting options:

• Bold
• Italic
• Link

You can use this setting type to capture formatted text content, such as introductory brand content on the homepage.

For example, the following setting generates the following output:

When accessing the value of an inline_richtext type setting, data is returned in one of the following formats:

• A string that contains the entered content.
• An empty object, if nothing has been entered.

---

Anchor to [object Object]link_list

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 this setting type to capture a menu selection, such as the menu to use for footer links.

For example, the following setting generates the following output:

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

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

---

Anchor to [object Object]liquid

A setting of type liquid outputs a multi-line text field that accepts HTML and limited Liquid markup. You can use this setting type 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:

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

• A string that contains the entered content.
• An empty object, if nothing has been entered.

Anchor to LimitationsLimitations

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

• layout
• content_for_header
• content_for_layout
• content_for_index
• section
• javascript
• stylesheet
• schema
• settings

However, liquid settings can access the following:

• Global Liquid objects
• Template specific objects like collection, product, etc. (within their respective templates)
• Standard Liquid tags and filters

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:

---

Anchor to [object Object]metaobject

A metaobject setting allows merchants to select metaobject entries of a designated type through a picker interface. This setting supports both standard and custom metaobject definitions:

1. Standard metaobject definitions: These are readily available in the theme editor and do not need to be pre-enabled on a shop. An example of a standard metaobject is the product_review metaobject. Learn more about current standard metaobject definitions.
2. Custom metaobject definitions: These are designed for custom themes and require the metaobject definition to already exist. Note that custom metaobject definitions are not allowed in themes listed on the Theme Store. An example of a custom metaobject would be an author metaobject.

Additionally, apps can utilize metaobject settings with their own app-owned metaobject definitions and entries.

metaobject type settings have the following attributes, in addition to the standard attributes of an input setting:

A metaobject setting value can be either of the following formats:

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

Anchor to Standard metaobject exampleStandard metaobject example

Anchor to Custom metaobject exampleCustom metaobject example

Anchor to LimitationsLimitations

• Only a single metaobject_type is supported at a time, as defined in the setting's schema.
• In order for themes to meet publishing guidelines for the Shopify Theme Store, only standard definitions can be used. Custom or app owned definitions cannot be used.
• When referencing a custom or app created metaobject_type, the definition must exist on the shop and be available to the storefront. If either condition isn't met, the setting will show an error in the theme editor.

Anchor to Usage in appsUsage in apps

Apps can leverage metaobject settings in their app blocks or embeds to enhance theme functionality. By creating metaobject definitions under reserved namespaces, apps can offer advanced configuration options for merchants while maintaining a simple user experience.

Consider an app designed to improve brand storytelling through customer testimonials. Here's a potential implementation:

1. Create a custom metaobject definition named Customer Testimonial
2. Use app blocks to collect customer data on a post-purchase page
3. Write this data as Customer Testimonial metaobject entries
4. Provide a Testimonial app block with a metaobject setting that uses the Customer Testimonial metaobject type
5. Access the metaobject setting value in Liquid to display the selected testimonials

---

Anchor to [object Object]metaobject_list

A metaobject_list setting allows merchants to select multiple metaobject entries of a designated type through a picker interface. This setting supports both standard and custom metaobject definitions:

1. Standard metaobject definitions: These are readily available in the theme editor and do not need to be pre-enabled on a shop. An example of a standard metaobject is the product_review metaobject. Learn more about current standard metaobject definitions.
2. Custom metaobject definitions: These are designed for custom themes and require the metaobject definition to already exist. Note that custom metaobject definitions are not allowed in themes listed on the Theme Store. An example of a custom metaobject would be an author metaobject.

Additionally, apps can utilize metaobject_list settings with their own app-owned metaobject definitions and entries.

metaobject_list type settings have the following attributes, in addition to the standard attributes of an input setting:

A metaobject_list setting value can be either of the following formats:

• An array of metaobject objects

  The array supports pagination using the paginate tag. You can also append .count to the setting key to return the number of metaobject entries in the array.

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

Anchor to Standard metaobject list exampleStandard metaobject list example

Anchor to Custom metaobject list exampleCustom metaobject list example

Anchor to LimitationsLimitations

• Only a single metaobject_type is supported at a time, as defined in the setting's schema.
• In order for themes to meet publishing guidelines for the Shopify Theme Store, custom or app owned definitions cannot be used.
• When referencing a custom or app created metaobject_type, the definition must exist on the shop and be available to the storefront. If either condition isn't met, the setting will show an error in the theme editor.

Anchor to Usage in appsUsage in apps

Apps can leverage metaobject_list settings in their app blocks or embeds to enhance theme functionality. By creating metaobject definitions under reserved namespaces, apps can offer advanced configuration options for merchants while maintaining a simple user experience. Using the same example as above, a Testimonials app-block could allow merchants to select multiple testimonial entries. The metaobject_list setting would make this implementation possible.

---

Anchor to [object Object]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 this setting type 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:

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

• A page object.

To ensure backwards compatibility with legacy resource-based settings, outputting the setting directly will return the object's handle.

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

---

Anchor to [object Object]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 this setting type to capture a product selection, such as the product to feature on the homepage.

For example, the following setting generates the following output:

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

• A product object.

To ensure backwards compatibility with legacy resource-based settings, outputting the setting directly will return the object's handle.

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

---

Anchor to [object Object]product_list

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

In addition to the standard attributes of an input setting, product_list type settings have the following attributes:

When accessing the value of a product_list type setting, data is returned in one of the following formats:

• An array of product objects

The array supports pagination using the paginate tag. You can also append .count to the setting key to return the number of products in the array.

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

---

Anchor to [object Object]richtext

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

• Bold
• Italic
• Underline
• Link
• Paragraph
• Unordered list

You can use this setting type to capture formatted text content, such as introductory brand content on the homepage.

For example, the following setting generates the following output:

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

• A string that contains the entered content.
• An empty object, if nothing has been entered.

Anchor to [object Object]default

The default attribute isn't required. However, if it's used, then only <p> or <ul> tags are supported as top-level elements.

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

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

---

Anchor to [object Object]text_alignment

A setting of type text_alignment outputs a SegmentedControl field with icons. In addition to the standard attributes of an input setting, text_alignment type settings support the following attribute:

The following default values can't be changed to a different value:

For example, the following setting generates the following output:

When you access the value of a text_alignment type setting, data is returned as a string.

---

Anchor to [object Object]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 this setting type 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:

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

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

---

Anchor to [object Object]video

A setting of type video outputs a video picker that's automatically populated with the available videos from the Files section of the Shopify admin. The merchant also has the option to upload new videos.

For example, the following setting generates the following output:

The video type setting also accepts metafields of type file_reference as a dynamic source.

When accessing the value of a video type setting, data is returned in one of the following formats:

• A video object.
• nil, if:
  • no selection has been made,
  • the selection no longer exists, or
  • the selection is a file_reference metafield that points to a non-video file.

---

Anchor to [object Object]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:

This setting type 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:

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

• 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:

---

Anchor to Create linksCreate links

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:

---