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:
Category Object Properties:
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
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
listtype 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:
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
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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Example:
{
"id": "card_border",
"type": "border",
"label": "Card Border",
"info": "Set the border for cards.",
"width": 2,
"style": "solid",
"color": "#cccccc"
}Content linking
Menu
A menu selector for choosing from a list of predefined menus. Useful for linking to navigation menus.
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.
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.
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.
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.
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.
Example:
{
"id": "spacer_1",
"type": "spacer",
"conditions": []
}Separator
A horizontal line that separates content. Does not have any configurable properties.
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.
Example:
{
"id": "secret_token",
"type": "hidden",
"default": "abc123",
"conditions": []
}Style Picker
A style selector that lets merchants choose a predefined color style for a section or block. The available styles are
defined by a corresponding style-editor setting in the theme settings. The styles_id property links the picker to
the editor by referencing the id of the style-editor setting.
The setting value is the id of the selected preset (e.g. "general", "dark", "pink"). In Liquid templates, you
can access it via section.settings.<id>.
Example (section schema):
{
"id": "sectionStyle",
"type": "style-picker",
"styles_id": "styles",
"default": "general",
"label": {
"en": "Color style",
"fi": "Värityyli"
},
"info": {
"en": "You can edit the color styles in the theme settings",
"fi": "Voit muokata värityylejä teeman asetuksista"
}
}In this example, styles_id is set to "styles", which must match the id of a style-editor setting defined in the
theme’s settings_schema.json.
Style Editor
A theme-level setting that defines a set of named color style presets. Each preset contains a collection of color
settings that merchants can customize. Sections and blocks reference these presets using the style-picker setting
type.
The style-editor is only used in theme settings (settings_schema.json). It defines both the editable color
fields and a list of presets with default values.
Preset object properties:
Example (theme settings):
{
"id": "styles",
"type": "style-editor",
"settings": [
{
"type": "title",
"label": { "en": "Background", "fi": "Tausta" }
},
{
"id": "background_color",
"type": "color",
"label": { "en": "Background color", "fi": "Taustaväri" },
"nullable": true
},
{
"id": "text_color",
"type": "color",
"label": { "en": "Text color", "fi": "Tekstin väri" },
"nullable": true
},
{
"type": "spacer"
},
{
"type": "title",
"label": { "en": "Buttons", "fi": "Napit" }
},
{
"id": "button_bg_color",
"type": "color",
"label": { "en": "Button background", "fi": "Napin taustaväri" },
"nullable": true
},
{
"id": "button_text_color",
"type": "color",
"label": { "en": "Button text", "fi": "Napin tekstin väri" },
"nullable": true
}
],
"presets": [
{
"id": "general",
"name": { "en": "Primary color", "fi": "Pääväri" },
"default": {
"background_color": "#ffffff",
"text_color": "#1a1a1a",
"button_bg_color": "#1a1a1a",
"button_text_color": "#ffffff"
}
},
{
"id": "dark",
"name": { "en": "Dark", "fi": "Tumma" },
"default": {
"background_color": "#000000",
"text_color": "#ffffff",
"button_bg_color": "#ffffff",
"button_text_color": "#000000"
}
}
]
}How style-picker and style-editor work together
The two setting types form a define-and-select pattern:
-
Define color styles in theme settings using
style-editor. This creates a set of named presets, each with customizable color fields. The merchant can edit the colors of each preset in the theme settings panel. -
Select a style in section or block settings using
style-picker. Thestyles_idproperty points to theidof thestyle-editorsetting, making the presets available for selection. -
The
style-pickerrenders each preset as a selectable button showing a preview of the preset’s colors. -
The stored value of a
style-pickersetting is the presetidstring (e.g."general","dark"). The actual color values are stored under thestyle-editorsetting in the theme configuration.
settings_schema.json section schema
┌──────────────────────┐ ┌──────────────────────┐
│ style-editor │ │ style-picker │
│ id: "styles" ◄────┼────────────────┤ styles_id: "styles"│
│ presets: │ │ default: "general" │
│ - general │ └──────────────────────┘
│ - dark │
│ - light │
│ settings: │
│ - background_color│
│ - text_color │
│ - button_bg_color│
└──────────────────────┘