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

| Property                  | Type             | Description                                                                                        |
| ------------------------- | ---------------- | -------------------------------------------------------------------------------------------------- |
| `name`                    | string           | Internal identifier for the theme.                                                                 |
| `theme_name`              | string           | Public name of the theme, shown to merchants.                                                      |
| `theme_author`            | string           | Name of the theme author.                                                                          |
| `theme_image`             | string           | Path to the theme preview image (e.g., `assets/theme-image.jpg`).                                  |
| `theme_documentation_url` | string or object | URL to the theme documentation. Can be a string or a localized object with language codes as keys. |
| `theme_demo_url`          | string           | URL to a live demo of the theme.                                                                   |
| `section_categories`      | array            | List of section category objects. Each object has `id` and `name` (can be localized).              |
| `block_categories`        | array            | List of block category objects. Each object has `id` and `name` (can be localized).                |
| `settings`                | array or object  | List or structure of settings, groups, or blocks (see below for grouping and types).               |

**Category Object Properties:**

| Property | Type   | Description                         |
| -------- | ------ | ----------------------------------- |
| `id`     | string | Unique identifier for the category. |
| `name`   | object | Localized name for the category.    |

**Example**: `settings_schema.json`

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

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

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

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

| Property   | Type    | Description                                            |
| ---------- | ------- | ------------------------------------------------------ |
| `name`     | string  | Name of the preset.                                    |
| `default`  | boolean | If true, this preset is the default one.               |
| `settings` | object  | Object containing the settings values for this preset. |

**Example**: `settings_data.json`

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

```json
{
  "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.

```json
{
  "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.

> **Info:**
  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`

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

| Property      | Type             | Description                                                |
| ------------- | ---------------- | ---------------------------------------------------------- |
| `id`          | string           | Unique identifier for the setting.                         |
| `type`        | string           | Type of the setting (see below).                           |
| `label`       | string or object | Display label (can be localized).                          |
| `info`        | string or object | Optional help text (can be localized, markdown supported). |
| `default`     | any              | Default value for the setting.                             |
| `conditions`  | array            | Show/hide logic based on other settings. Read more about   |
| `placeholder` | string or object | Placeholder text (where applicable).                       |
| `options`     | array            | Options 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:**

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

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

### Supported Conditions

| Operator | Description                      | Example condition   | Example usage                                 |
| -------- | -------------------------------- | ------------------- | --------------------------------------------- |
| eq       | Equals                           | `show_text eq true` | Show if `show_text` is `true`                 |
| gt       | Greater than                     | `value gt 10`       | Show if `value` is greater than 10            |
| gte      | Greater or equal                 | `value gte 5`       | Show if `value` is greater than or equal to 5 |
| lt       | Less than                        | `value lt 100`      | Show if `value` is less than 100              |
| lte      | Less or equal                    | `value lte 50`      | Show if `value` is less than or equal to 50   |
| contains | String contains value            | `text contains foo` | Show if `text` contains the substring `foo`   |
| in       | Value is in comma-separated list | `option in a,b,c`   | Show if `option` is either `a`, `b`, or `c`   |

### More Examples

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

```json
{
  "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:

```json
{
  "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.

| Property      | Type          | Description         |
| ------------- | ------------- | ------------------- |
| `id`          | string        | Unique identifier.  |
| `type`        | string        | Must be `text`.     |
| `label`       | string/object | Display label.      |
| `info`        | string/object | Optional help text. |
| `default`     | string        | Default value.      |
| `placeholder` | string/object | Placeholder text.   |

**Example:**

```json
{
  "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.

| Property      | Type          | Description         |
| ------------- | ------------- | ------------------- |
| `id`          | string        | Unique identifier.  |
| `type`        | string        | Must be `textarea`. |
| `label`       | string/object | Display label.      |
| `info`        | string/object | Optional help text. |
| `default`     | string        | Default value.      |
| `placeholder` | string/object | Placeholder text.   |

**Example:**

```json
{
  "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).

| Property   | Type          | Description                                       |
| ---------- | ------------- | ------------------------------------------------- |
| `id`       | string        | Unique identifier.                                |
| `type`     | string        | Must be `color`.                                  |
| `label`    | string/object | Display label.                                    |
| `info`     | string/object | Optional help text.                               |
| `default`  | string        | Default color value (e.g. `#ffffff`).             |
| `nullable` | boolean       | If true, user can clear the color (no value set). |

**Example:**

```json
{
  "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.

| Property  | Type          | Description                        |
| --------- | ------------- | ---------------------------------- |
| `id`      | string        | Unique identifier.                 |
| `type`    | string        | Must be `select`.                  |
| `label`   | string/object | Display label.                     |
| `info`    | string/object | Optional help text.                |
| `default` | string        | Default selected value.            |
| `options` | array         | Array of `{label, value}` objects. |

**Example:**

```json
{
  "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.

| Property  | Type          | Description            |
| --------- | ------------- | ---------------------- |
| `id`      | string        | Unique identifier.     |
| `type`    | string        | Must be `checkbox`.    |
| `label`   | string/object | Display label.         |
| `info`    | string/object | Optional help text.    |
| `default` | boolean       | Default checked state. |

**Example:**

```json
{
  "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.

| Property  | Type          | Description                        |
| --------- | ------------- | ---------------------------------- |
| `id`      | string        | Unique identifier.                 |
| `type`    | string        | Must be `radio`.                   |
| `label`   | string/object | Display label.                     |
| `info`    | string/object | Optional help text.                |
| `default` | string        | Default selected value.            |
| `options` | array         | Array of `{label, value}` objects. |

**Example:**

```json
{
  "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.

| Property | Type | Description |
| -------- | ---- | ----------- |

**Example:**

```json
{
  "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.

| Property     | Type          | Description                            |
| ------------ | ------------- | -------------------------------------- |
| `id`         | string        | Unique identifier.                     |
| `type`       | string        | Must be `range`.                       |
| `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 the slider.              |
| `hide_value` | boolean       | If true, hides the displayed value.    |
| `unit`       | string        | Optional unit label (e.g., `%`, `px`). |

**Example:**

````json
{
  "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.

| Property  | Type          | Description                                |
| --------- | ------------- | ------------------------------------------ |
| `id`      | string        | Unique identifier.                         |
| `type`    | string        | Must be `datetime`.                        |
| `label`   | string/object | Display label.                             |
| `info`    | string/object | Optional help text.                        |
| `default` | string        | Default date/time value (ISO 8601 format). |

**Example:**

```json
{
  "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.

| Property  | Type          | Description                                 |
| --------- | ------------- | ------------------------------------------- |
| `id`      | string        | Unique identifier.                          |
| `type`    | string        | Must be `richtext`.                         |
| `label`   | string/object | Display label.                              |
| `info`    | string/object | Optional help text.                         |
| `default` | string        | Default HTML content.                       |
| `size`    | string        | Size of the editor: `xs`, `sm`, `md`, `lg`. |
| `mode`    | string        | Editor mode: `simple`, `full`.              |

**Example:**

```json
{
  "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.

| Property  | Type          | Description              |
| --------- | ------------- | ------------------------ |
| `id`      | string        | Unique identifier.       |
| `type`    | string        | Must be `image-picker`.  |
| `label`   | string/object | Display label.           |
| `info`    | string/object | Optional help text.      |
| `default` | string        | Default image URL or ID. |

**Example:**

```json
{
  "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:

```liquid
{{ 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.

| Property   | Type          | Description                                      |
| ---------- | ------------- | ------------------------------------------------ |
| `id`       | string        | Unique identifier.                               |
| `type`     | string        | Must be `font-picker`.                           |
| `label`    | string/object | Display label.                                   |
| `info`     | string/object | Optional help text.                              |
| `default`  | string        | Default font value.                              |
| `families` | array         | Array of font family strings.                    |
| `nullable` | boolean       | If true, user can clear the font (no value set). |

**Example:**

```json
{
  "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.

| Property                    | Type             | Description                                                           |
| --------------------------- | ---------------- | --------------------------------------------------------------------- |
| `id`                        | string           | Unique identifier.                                                    |
| `type`                      | string           | Must be `margin`, `padding`, or `border-radius`.                      |
| `label`                     | string/object    | Display label.                                                        |
| `info`                      | string/object    | Optional help text.                                                   |
| `margin`/`padding`/`radius` | number or object | Value for all sides, or object with `top`, `right`, `bottom`, `left`. |
| `apply_to_all_sides`        | boolean          | If true, applies the value to all sides.                              |
| `max`                       | number           | Maximum value for the setting.                                        |
| `min`                       | number           | Minimum value for the setting.                                        |
| `step`                      | number           | Step size for incrementing/decrementing.                              |
| `disable_horizontal`        | boolean          | If true, disables horizontal (left/right) controls.                   |
| `disable_vertical`          | boolean          | If true, disables vertical (top/bottom) controls.                     |

**Examples:**

Single value for all sides (with toggle):

```json
{
  "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:

```json
{
  "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:

```json
{
  "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.

| Property | Type          | Description                                                  |
| -------- | ------------- | ------------------------------------------------------------ |
| `id`     | string        | Unique identifier.                                           |
| `type`   | string        | Must be `border`.                                            |
| `label`  | string/object | Display label.                                               |
| `info`   | string/object | Optional help text.                                          |
| `width`  | number        | Border width in pixels.                                      |
| `style`  | string        | Border style: `none`, `solid`, `dashed`, `dotted`, `double`. |
| `color`  | string        | Border color in hex.                                         |

**Example:**

```json
{
  "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.

| Property  | Type          | Description          |
| --------- | ------------- | -------------------- |
| `id`      | string        | Unique identifier.   |
| `type`    | string        | Must be `menu`       |
| `label`   | string/object | Display label.       |
| `info`    | string/object | Optional help text.  |
| `default` | string        | Default value or ID. |

**Example:**

```json
{
  "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.

| Property      | Type          | Description                                                         |
| ------------- | ------------- | ------------------------------------------------------------------- |
| `id`          | string        | Unique identifier.                                                  |
| `type`        | string        | Must be `category`, `manufacturer`, `product`, `article`, or `page` |
| `label`       | string/object | Display label.                                                      |
| `info`        | string/object | Optional help text.                                                 |
| `default`     | string        | Default value or ID.                                                |
| `placeholder` | string/object | Placeholder text.                                                   |

**Example:**

```json
{
  "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.

| Property         | Type          | Description                                                                               |
| ---------------- | ------------- | ----------------------------------------------------------------------------------------- |
| `id`             | string        | Unique identifier.                                                                        |
| `type`           | string        | Must be `url`.                                                                            |
| `label`          | string/object | Display label.                                                                            |
| `info`           | string/object | Optional help text.                                                                       |
| `default`        | string        | Default value or ID.                                                                      |
| `placeholder`    | string/object | Placeholder text.                                                                         |
| `include_text`   | boolean       | If true, link text is input as well. Link might not be selected when this option is used! |
| `include_target` | boolean       | If true, user can set target (e.g., `_blank`).                                            |

**Example:**

```json
{
  "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.

| Property | Type          | Description         |
| -------- | ------------- | ------------------- |
| `id`     | string        | Unique identifier.  |
| `type`   | string        | Must be `title`.    |
| `label`  | string/object | Display label.      |
| `info`   | string/object | Optional help text. |

**Example:**

```json
{
  "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.

| Property | Type          | Description         |
| -------- | ------------- | ------------------- |
| `id`     | string        | Unique identifier.  |
| `type`   | string        | Must be `label`.    |
| `label`  | string/object | Display label.      |
| `info`   | string/object | Optional help text. |

**Example:**

```json
{
  "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.

| Property | Type   | Description        |
| -------- | ------ | ------------------ |
| `id`     | string | Unique identifier. |
| `type`   | string | Must be `spacer`.  |

**Example:**

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

#### Separator

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

| Property | Type   | Description          |
| -------- | ------ | -------------------- |
| `id`     | string | Unique identifier.   |
| `type`   | string | Must be `separator`. |

**Example:**

```json
{
  "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.

| Property  | Type   | Description        |
| --------- | ------ | ------------------ |
| `id`      | string | Unique identifier. |
| `type`    | string | Must be `hidden`.  |
| `default` | any    | Default value.     |

**Example:**

```json
{
  "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.

| Property    | Type          | Description                                                                                     |
| ----------- | ------------- | ----------------------------------------------------------------------------------------------- |
| `id`        | string        | Unique identifier for the setting.                                                              |
| `type`      | string        | Must be `style-picker`.                                                                         |
| `styles_id` | string        | The `id` of the `style-editor` setting in the theme settings that defines the available styles. |
| `label`     | string/object | Display label (can be localized).                                                               |
| `info`      | string/object | Optional help text (can be localized).                                                          |
| `default`   | string        | The `id` of the preset to use by default (e.g. `"general"`).                                    |

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

```json
{
  "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.

| Property   | Type   | Description                                                                                                                       |
| ---------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `id`       | string | Unique identifier. Referenced by `style-picker` settings via `styles_id`.                                                         |
| `type`     | string | Must be `style-editor`.                                                                                                           |
| `settings` | array  | Array of setting definitions (typically `color` type) that make up each style. Supports `title` and `spacer` for visual grouping. |
| `presets`  | array  | Array of preset objects defining the available color styles.                                                                      |

**Preset object properties:**

| Property  | Type          | Description                                                           |
| --------- | ------------- | --------------------------------------------------------------------- |
| `id`      | string        | Unique identifier for the preset (e.g. `"general"`, `"dark"`).        |
| `name`    | string/object | Display name for the preset (can be localized).                       |
| `default` | object        | Key-value pairs mapping each setting `id` to its default color value. |

**Example** (theme settings):

```json
{
  "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:

1. **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.

2. **Select** a style in section or block settings using `style-picker`. The `styles_id` property points to the `id` of
   the `style-editor` setting, making the presets available for selection.

3. The `style-picker` renders each preset as a selectable button showing a preview of the preset's colors.

4. The **stored value** of a `style-picker` setting is the preset `id` string (e.g. `"general"`, `"dark"`). The actual
   color values are stored under the `style-editor` setting 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│
└──────────────────────┘
```