Skip to Content

Settings

Learn how to add and configure settings for your Finqu theme, allowing merchants to customize their theme’s appearance and behavior.

Theme, Section, and Block Settings

There are three main types of settings in a Finqu theme. Theme-level settings are global, while section and block settings provide granular control over specific parts of the storefront. Understanding this distinction helps you organize your theme’s configuration for maximum flexibility and usability.

Theme settings (settings_schema.json)

These settings apply to the entire store and control global aspects such as colors, fonts, and layout options. They are defined in the settings_schema.json file at the root of your theme’s config directory. Their values are stored in settings_data.json and can be accessed throughout the theme using the settings object. Merchants use these to personalize the overall look and feel of their store. Following properties are supported:

PropertyTypeDescription
namestringInternal identifier for the theme.
theme_namestringPublic name of the theme, shown to merchants.
theme_authorstringName of the theme author.
theme_imagestringPath to the theme preview image (e.g., assets/theme-image.jpg).
theme_documentation_urlstring or objectURL to the theme documentation. Can be a string or a localized object with language codes as keys.
theme_demo_urlstringURL to a live demo of the theme.
section_categoriesarrayList of section category objects. Each object has id and name (can be localized).
block_categoriesarrayList of block category objects. Each object has id and name (can be localized).
settingsarray or objectList or structure of settings, groups, or blocks (see below for grouping and types).

Category Object Properties:

PropertyTypeDescription
idstringUnique identifier for the category.
nameobjectLocalized name for the category.

Example: settings_schema.json

{ "name": "Theme identifier", "theme_name": "Theme public name", "theme_author": "Author of the theme", "theme_image": "assets/theme-image.jpg", "theme_documentation_url": "https://theme.doc.url", "theme_demo_url": "https://theme.demo.url", "section_categories": [ { "id": "theme-section-category", "name": { "en": "Category name", "fi": "Kategorian nimi" } } ], "block_categories": [ { "id": "theme-block-category", "name": { "en": "Category name", "fi": "Kategorian nimi" } } ], "settings": [ // List of settings (see below) ] }

Section settings

These settings are specific to individual sections (such as a hero banner, product grid, or footer) and allow merchants to customize the appearance and behavior of each section independently. Section settings are defined within each section’s configuration file with a {% schema %} tag. They can include options like background images, text colors, and layout choices. Section settings are stored in the settings_data.json file under the corresponding section ID.

Example: sections/example-section.liquid

<div> <h2>{{ section.settings.section_title }}</h2> <div style="background-color: {{ section.settings.section_background_color }};"> <!-- Section content goes here --> </div> </div> {% schema %} { "name": "Example Section", "settings": [ { "type": "text", "id": "section_title", "label": "Section Title", "default": "Welcome to Our Store" }, { "type": "color", "id": "section_background_color", "label": "Background Color", "default": "#ffffff" } ] } {% endschema %}

Block settings

Blocks are reusable components within sections (like a single slide in a carousel or a feature item in a list). Block-level settings control the content and style of each block and are defined within the section or block configuration.

Block settings are stored in the settings_data.json file under the corresponding section ID and block ID. They allow merchants to customize individual instances of a block without affecting others.

Example: blocks/example-block.liquid

<div> <h3>{{ block.settings.block_title }}</h3> <p>{{ block.settings.block_description }}</p> <img src="{{ block.settings.block_image | img_url: 'medium' }}" alt="{{ block.settings.block_title }}"> </div> {% schema %} { "name": "Example Block", "settings": [ { "type": "text", "id": "block_title", "label": "Block Title", "default": "Feature Item" }, { "type": "textarea", "id": "block_description", "label": "Block Description", "default": "This is a feature item." }, { "type": "image-picker", "id": "block_image", "label": "Block Image" } ] } {% endschema %}

settings_data.json

The settings_data.json file stores the current values of all settings defined in settings_schema.json. This file contains the current state of the settings which is updated whenever a merchant changes a setting in the theme editor. At the same level developer may also define presets for the theme. Presets are predefined configurations that can be applied to settings. They allow merchants to quickly set up their store with a specific look and feel. Presets can include a combination of colors, fonts, and other settings.

Example: settings_data.json

{ "current": { "text_color": "#000000", "background_color": "#ffffff", // Other settings values }, "presets": [ { "name": "Default", "settings": { "text_color": "#000000", "background_color": "#ffffff" } }, { "name": "Dark Mode", "settings": { "text_color": "#ffffff", "background_color": "#000000" } } ] }

Presets

Presets are predefined configurations that can be applied to settings. They allow merchants to quickly set up their store with a specific look and feel. Presets can include a combination of colors, fonts, and other settings. Presets are defined in the settings_data.json file and can be applied to the theme through the theme editor.

Preset Properties

PropertyTypeDescription
namestringName of the preset.
defaultbooleanIf true, this preset is the default one.
settingsobjectObject containing the settings values for this preset.

Example: settings_data.json

{ "current": { // Current settings values }, "presets": { "default": { "name": "Default", "default": true, "settings": { "text_color": "#000000", "background_color": "#ffffff" } }, "dark_mode": { "name": "Dark Mode", "settings": { "text_color": "#ffffff", "background_color": "#000000" } } } }

Grouping Settings

You can organize settings into logical groups to improve usability and make complex configuration panels easier to navigate. Grouping is especially useful for sections with many settings or when you want to separate settings into categories, tabs, or blocks.

Grouping theme settings

Settings can be organized into pages, which are sections that contain a list of settings. Each page can have its own title and description. Pages can be nested within other pages to create a hierarchy of settings. In order to do this, you can use the setting-page setting type. Commonly a heading is defined at the top of the new page. Here’s how to define a page:

{ "type": "setting_page", "label": "Colors", "settings": [ { "type": "heading", "label": "Primary colors", "subheading": "These are the primary colors of the theme, which define the color palette of your online store and highlight your brand's identity." }, { "type": "color", "id": "primary_color", "label": "Primary Color", "default": "#0055ff" }, { "type": "color", "id": "secondary_color", "label": "Secondary Color", "default": "#ff5500" } ] }

Nesting pages

You can nest pages within other pages to create a hierarchy of settings. This is useful for organizing complex settings structures. Each page can have its own title and description.

{ "type": "setting_page", "label": "Colors", "settings": [ { "type": "setting_page", "label": "Primary colors", "settings": [ { "type": "color", "id": "primary_color", "label": "Primary Color", "default": "#0055ff" }, { "type": "color", "id": "secondary_color", "label": "Secondary Color", "default": "#ff5500" } ] } ] }

Sections and Blocks

Sections can contain blocks, which are reusable components that can be added to a section. Each block can have its own settings and can be grouped into categories. Blocks can also be nested within other blocks.

Tabs and Lists

Settings can be grouped using either tabs or list as the list_type:

  • Tabs: Display settings in horizontal tabbed navigation. Tabs can be nested up to two levels deep. Each tab row should contain no more than 4 items for optimal usability. If you need more than 4 groups, use the list type instead.
  • List: Display groups or settings in a vertical list. Use this when you have many groups or want a simpler, scrollable layout.

Tabs can be nested one level deep (i.e., you can have subtabs inside a tab), but avoid deeper nesting for clarity. For example, you can have main tabs, and each main tab can have its own set of subtabs. If you need to organize more deeply, consider breaking the settings into multiple sections or using lists.

Setting Blocks

Setting blocks are reusable components that can be added to sections. Each block can have its own settings and type. Setting blocks can be used to create dynamic content areas, such as slideshows or product lists. You can define a call_to_action for adding new blocks, and you can also make the blocks sortable. If you define is_sortable as true, the blocks will be displayed in a sortable list, allowing merchants to rearrange them easily.

Setting blocks must be defined in their own tab or list. You cannot mix them with other settings in the same group.

Example: sections/image-carousel.liquid

<div> <h2>{{ section.settings.carousel_title }}</h2> <div class="carousel"> {% for block in section.setting_blocks.slides %} {% if block.type == 'slide' %} <div class="slide"> <img src="{{ block.settings.image | img_url: 'medium' }}" alt="{{ block.settings.image_alt }}"> <p>{{ block.settings.image_caption }}</p> </div> {% endif %} {% endfor %} </div> </div> {% schema %} { "name": "Image Carousel", "settings": { "list_type": "tabs", "groups": [ { "title": "General", "settings": [ { "type": "text", "id": "carousel_title", "label": "Carousel Title", "default": "Featured Images" } ] }, { "title": "Slides", "is_sortable": true, "call_to_action": { "label": "Add Slide" }, "id": "slides", "setting_blocks": [ { "type": "slide", "title": "Slide", "settings": [ { "type": "image-picker", "id": "image", "label": "Image" }, { "type": "text", "id": "image_alt", "label": "Image Alt Text" }, { "type": "textarea", "id": "image_caption", "label": "Image Caption" } ] } ] } ] } } {% endschema %}

Common Properties

Setting types support these base properties:

PropertyTypeDescription
idstringUnique identifier for the setting.
typestringType of the setting (see below).
labelstring or objectDisplay label (can be localized).
infostring or objectOptional help text (can be localized, markdown supported).
defaultanyDefault value for the setting.
conditionsarrayShow/hide logic based on other settings. Read more about
placeholderstring or objectPlaceholder text (where applicable).
optionsarrayOptions for select/radio types.

Localization

All user-facing text in settings, such as label, info, and placeholder, can be localized. To provide translations, use an object with language codes as keys. If a string is provided instead of an object, it will be used as the default for all languages.

Examples:

{ "label": { "en": "Store Name", "fi": "Kaupan nimi" }, "info": { "en": "Enter the name of your store.", "fi": "Syötä kaupan nimi." }, "placeholder": { "en": "e.g. My Awesome Store", "fi": "esim. Mahtava Kauppa" } }

If you only provide a string, it will be used for all languages:

{ "label": "Store Name" }

Conditional Rendering

Settings can be shown or hidden based on other setting values using the conditions property. This allows you to create dynamic and context-aware settings panels.

Basic Example

Show a text field only if a checkbox is checked:

{ "type": "checkbox", "id": "show_text", "label": "Show text field", "default": false }, { "type": "text", "id": "conditional_text", "label": "This appears if checkbox is checked", "conditions": ["show_text eq true"] }

Multiple Conditions

You can use multiple conditions. All conditions must be true for the setting to be shown:

{ "type": "text", "id": "advanced_text", "label": "Advanced text", "conditions": [ "show_text eq true", "another_setting gt 5" ] }

Supported Conditions

OperatorDescriptionExample conditionExample usage
eqEqualsshow_text eq trueShow if show_text is true
gtGreater thanvalue gt 10Show if value is greater than 10
gteGreater or equalvalue gte 5Show if value is greater than or equal to 5
ltLess thanvalue lt 100Show if value is less than 100
lteLess or equalvalue lte 50Show if value is less than or equal to 50
containsString contains valuetext contains fooShow if text contains the substring foo
inValue is in comma-separated listoption in a,b,cShow if option is either a, b, or c

More Examples

Show a setting only if a select value is one of several options:

{ "type": "select", "id": "color_scheme", "label": "Color scheme", "options": [ { "value": "light", "label": "Light" }, { "value": "dark", "label": "Dark" }, { "value": "auto", "label": "Auto" } ] }, { "type": "color", "id": "custom_color", "label": "Custom color", "conditions": ["color_scheme in dark,auto"] }

Show a setting if a numeric value is greater than or equal to 10:

{ "type": "range", "id": "items_count", "label": "Number of items", "min": 1, "max": 20 }, { "type": "text", "id": "extra_note", "label": "Extra note", "conditions": ["items_count gte 10"] }

Setting Types

This reference lists all available setting types and their supported properties for use in your theme or editor configuration schemas.

Text

A single-line text input for short strings such as names, titles, or custom values. Useful for any freeform text entry.

PropertyTypeDescription
idstringUnique identifier.
typestringMust be text.
labelstring/objectDisplay label.
infostring/objectOptional help text.
defaultstringDefault value.
placeholderstring/objectPlaceholder text.

Example:

{ "id": "store_name", "type": "text", "label": "Store Name", "info": "Enter the name of your store.", "default": "", "placeholder": "e.g. My Awesome Store" }

Textarea

A multi-line text input for longer content, such as descriptions or notes. Supports markdown in some editors.

PropertyTypeDescription
idstringUnique identifier.
typestringMust be textarea.
labelstring/objectDisplay label.
infostring/objectOptional help text.
defaultstringDefault value.
placeholderstring/objectPlaceholder text.

Example:

{ "id": "store_description", "type": "textarea", "label": "Store Description", "info": "Describe your store for customers.", "default": "", "placeholder": "Type a short description..." }

Color

A color picker input for selecting a color value, typically in hex format. Useful for theme colors, backgrounds, etc. The nullable property allows the user to clear the selected color (set it to no value).

PropertyTypeDescription
idstringUnique identifier.
typestringMust be color.
labelstring/objectDisplay label.
infostring/objectOptional help text.
defaultstringDefault color value (e.g. #ffffff).
nullablebooleanIf true, user can clear the color (no value set).

Example:

{ "id": "primary_color", "type": "color", "label": "Primary Color", "info": "Main color for buttons and highlights.", "default": "#0055ff", "nullable": true }

Select

A dropdown select input for choosing one value from a list of options. Each option has a label and a value.

PropertyTypeDescription
idstringUnique identifier.
typestringMust be select.
labelstring/objectDisplay label.
infostring/objectOptional help text.
defaultstringDefault selected value.
optionsarrayArray of {label, value} objects.

Example:

{ "id": "layout_style", "type": "select", "label": "Layout Style", "info": "Choose the layout for your store.", "default": "grid", "options": [ { "label": "Grid", "value": "grid" }, { "label": "List", "value": "list" } ] }

Checkbox

A boolean input for toggling a setting on or off. Useful for enabling/disabling features.

PropertyTypeDescription
idstringUnique identifier.
typestringMust be checkbox.
labelstring/objectDisplay label.
infostring/objectOptional help text.
defaultbooleanDefault checked state.

Example:

{ "id": "show_banner", "type": "checkbox", "label": "Show Banner", "info": "Display a promotional banner at the top.", "default": true }

Radio

A group of radio buttons for selecting one value from a set. Each option has a label and a value.

PropertyTypeDescription
idstringUnique identifier.
typestringMust be radio.
labelstring/objectDisplay label.
infostring/objectOptional help text.
defaultstringDefault selected value.
optionsarrayArray of {label, value} objects.

Example:

{ "id": "theme_mode", "type": "radio", "label": "Theme Mode", "info": "Choose between light and dark mode.", "default": "light", "options": [ { "label": "Light", "value": "light" }, { "label": "Dark", "value": "dark" } ] }

Radio Pill

A radio group styled as pill buttons. Functionally identical to radio, but visually distinct. Do not use with more than 5 options.

PropertyTypeDescription

Example:

{ "id": "button_shape", "type": "radio-pill", "label": "Button Shape", "info": "Choose the shape of buttons.", "default": "rounded", "options": [ { "label": "Rounded", "value": "rounded" }, { "label": "Square", "value": "square" } ] }

Range

A numeric input for selecting a value from a range, displayed as a slider. Ideal for settings like volume or brightness.

PropertyTypeDescription
idstringUnique identifier.
typestringMust be range.
labelstring/objectDisplay label.
infostring/objectOptional help text.
defaultnumberDefault value.
minnumberMinimum value.
maxnumberMaximum value.
stepnumberStep size for the slider.
hide_valuebooleanIf true, hides the displayed value.
unitstringOptional unit label (e.g., %, px).

Example:

{ "id": "volume_level", "type": "range", "label": "Volume Level", "info": "Adjust the speaker volume.", "default": 50, "min": 0, "max": 100, "step": 1, "unit": "%" } ### Number A numeric input for entering a specific number. Can be used for quantities, prices, or any numeric value. | Property | Type | Description | |---------------|-------------------|-----------------------------------------------------| | `id` | string | Unique identifier. | | `type` | string | Must be `number`. | | `label` | string/object | Display label. | | `info` | string/object | Optional help text. | | `default` | number | Default value. | | `min` | number | Minimum value. | | `max` | number | Maximum value. | | `step` | number | Step size for incrementing/decrementing. | **Example:** ```json { "id": "item_quantity", "type": "number", "label": "Item Quantity", "info": "Enter the number of items.", "default": 1, "min": 1, "max": 100, "step": 1 }

Datetime

A date and time picker for selecting a specific date and time. Useful for scheduling or time-based settings.

PropertyTypeDescription
idstringUnique identifier.
typestringMust be datetime.
labelstring/objectDisplay label.
infostring/objectOptional help text.
defaultstringDefault date/time value (ISO 8601 format).

Example:

{ "id": "event_start", "type": "datetime", "label": "Event Start", "info": "Select the start date and time of the event.", "default": "2023-10-01T10:00:00Z" }

Richtext

A rich text editor for entering formatted content. Supports text styling, links, and other media.

PropertyTypeDescription
idstringUnique identifier.
typestringMust be richtext.
labelstring/objectDisplay label.
infostring/objectOptional help text.
defaultstringDefault HTML content.
sizestringSize of the editor: xs, sm, md, lg.
modestringEditor mode: simple, full.

Example:

{ "id": "page_content", "type": "richtext", "label": "Page Content", "info": "Edit the content of the page.", "default": "<p>Welcome to our store!</p>", "placeholder": "Type your content here...", "size": "md", "mode": "full" }

Image Picker

An image picker for selecting or uploading images. Can be used for logos, banners, or any image assets.

PropertyTypeDescription
idstringUnique identifier.
typestringMust be image-picker.
labelstring/objectDisplay label.
infostring/objectOptional help text.
defaultstringDefault image URL or ID.

Example:

{ "id": "logo_image", "type": "image-picker", "label": "Logo Image", "info": "Upload your store logo.", "default": "", "conditions": ["theme_style eq 'custom'"] }

When an image is selected, the setting returns an object in Liquid with the following properties:

  • src: The image URL.
  • offset_top: User-adjusted vertical offset (in pixels).
  • offset_left: User-adjusted horizontal offset (in pixels).
  • width: Image width (in pixels).
  • height: Image height (in pixels).

You can access these values in your Liquid templates, for example:

{{ settings.logo_image.src }} {{ settings.logo_image.offset_top }} {{ settings.logo_image.width }}

Font Picker

A font picker for selecting font families. Can be used to change the typography of text elements.

PropertyTypeDescription
idstringUnique identifier.
typestringMust be font-picker.
labelstring/objectDisplay label.
infostring/objectOptional help text.
defaultstringDefault font value.
familiesarrayArray of font family strings.
nullablebooleanIf true, user can clear the font (no value set).

Example:

{ "id": "body_font", "type": "font-picker", "label": "Body Font", "info": "Select the font for body text.", "default": "Arial", "families": [ "Arial", "Georgia" ], "nullable": true }

Margin, Padding, Border Radius

Inputs for CSS box model properties. Allow spacing and border radius adjustments. These settings can be used to control the spacing and shape of elements in your theme. Each type has its own main property: margin, padding, or radius (for border-radius). You can set a single value for all sides, or specify values for each side individually. The apply_to_all_sides property allows users to toggle between a single value for all sides or separate values for each side. You can also use disable_horizontal or disable_vertical to restrict the setting to only vertical or horizontal sides.

PropertyTypeDescription
idstringUnique identifier.
typestringMust be margin, padding, or border-radius.
labelstring/objectDisplay label.
infostring/objectOptional help text.
margin/padding/radiusnumber or objectValue for all sides, or object with top, right, bottom, left.
apply_to_all_sidesbooleanIf true, applies the value to all sides.
maxnumberMaximum value for the setting.
minnumberMinimum value for the setting.
stepnumberStep size for incrementing/decrementing.
disable_horizontalbooleanIf true, disables horizontal (left/right) controls.
disable_verticalbooleanIf true, disables vertical (top/bottom) controls.

Examples:

Single value for all sides (with toggle):

{ "id": "container_padding", "type": "padding", "label": "Container Padding", "info": "Set the padding for the container.", "padding": 20, "apply_to_all_sides": true }

Separate values for each side:

{ "id": "container_margin", "type": "margin", "label": "Container Margin", "info": "Set the margin for the container.", "margin": { "top": 10, "right": 15, "bottom": 10, "left": 15 }, "apply_to_all_sides": false }

Border radius with only top and bottom enabled:

{ "id": "button_radius", "type": "border-radius", "label": "Button Border Radius", "info": "Set the border radius for buttons.", "radius": { "top": 8, "bottom": 8 }, "disable_horizontal": true }

Border

A border setting for controlling the border of an element. Allows you to define the border width, style, and color.

PropertyTypeDescription
idstringUnique identifier.
typestringMust be border.
labelstring/objectDisplay label.
infostring/objectOptional help text.
widthnumberBorder width in pixels.
stylestringBorder style: none, solid, dashed, dotted, double.
colorstringBorder color in hex.

Example:

{ "id": "card_border", "type": "border", "label": "Card Border", "info": "Set the border for cards.", "width": 2, "style": "solid", "color": "#cccccc" }

Content linking

A menu selector for choosing from a list of predefined menus. Useful for linking to navigation menus.

PropertyTypeDescription
idstringUnique identifier.
typestringMust be menu
labelstring/objectDisplay label.
infostring/objectOptional help text.
defaultstringDefault value or ID.

Example:

{ "id": "related_products", "type": "menu", "label": "Menu", "info": "Select a menu to display.", "default": "" }

Category, Manufacturer, Product, Article, Page

Autocomplete selectors for various entities. Useful for linking or referencing other content.

PropertyTypeDescription
idstringUnique identifier.
typestringMust be category, manufacturer, product, article, or page
labelstring/objectDisplay label.
infostring/objectOptional help text.
defaultstringDefault value or ID.
placeholderstring/objectPlaceholder text.

Example:

{ "id": "related_products", "type": "product", "label": "Related Products", "info": "Select products related to this item.", "default": "", "placeholder": "Start typing to search..." }

URL

Autocomplete selector for URLs. Useful for linking or referencing other content.

PropertyTypeDescription
idstringUnique identifier.
typestringMust be url.
labelstring/objectDisplay label.
infostring/objectOptional help text.
defaultstringDefault value or ID.
placeholderstring/objectPlaceholder text.
include_textbooleanIf true, link text is input as well. Link might not be selected when this option is used!
include_targetbooleanIf true, user can set target (e.g., _blank).

Example:

{ "id": "related_products", "type": "url", "label": "Link", "placeholder": "Start typing to search...", "include_text": true, "include_target": true }

Other Types

Title

A section or group title, displayed as a heading. Does not have an input field.

PropertyTypeDescription
idstringUnique identifier.
typestringMust be title.
labelstring/objectDisplay label.
infostring/objectOptional help text.

Example:

{ "id": "general_settings", "type": "title", "label": "General Settings", "info": "Settings that apply to the entire store." }

Label

A display label that is not an input. Can be used for static text or instructions.

PropertyTypeDescription
idstringUnique identifier.
typestringMust be label.
labelstring/objectDisplay label.
infostring/objectOptional help text.

Example:

{ "id": "api_integration_label", "type": "label", "label": "API Integration", "info": "Settings for integrating with external APIs." }

Spacer

A simple component that adds vertical space between other components. Does not have any configurable properties.

PropertyTypeDescription
idstringUnique identifier.
typestringMust be spacer.

Example:

{ "id": "spacer_1", "type": "spacer", "conditions": [] }

Separator

A horizontal line that separates content. Does not have any configurable properties.

PropertyTypeDescription
idstringUnique identifier.
typestringMust be separator.

Example:

{ "id": "section_separator", "type": "separator", "conditions": [] }

Hidden

A hidden field that is not shown in the UI. Can be used to store values that should not be directly editable.

PropertyTypeDescription
idstringUnique identifier.
typestringMust be hidden.
defaultanyDefault value.

Example:

{ "id": "secret_token", "type": "hidden", "default": "abc123", "conditions": [] }
Last updated on