Theme settings

Settings let hosts customise your theme (colors, labels, toggles) without touching code. You declare them in config/settings_schema.json; Stayblox renders the form, and your templates read the values from the settings global.

The format and example below are generated from the platform's reference theme, so they stay in sync with what the platform accepts.

Theme settings let hosts customise your theme without editing code. You declare them in config/settings_schema.json; Stayblox renders the form, and your templates read the values from the settings global.

Format

The file is an array of sections, each with a name and a list of fields. Each field has:

Property	Meaning
id	The setting key. Your templates read it as settings.<id>.
type	Input type (see below).
label	Label shown in the settings form.
default	Default value before the host changes anything.
fields	For a grid field only: nested fields grouped visually (their ids are still top-level settings).

Field types in use

image_picker, color_picker, text, textarea, radio, select, code_editor

Example: config/settings_schema.json

[
  {
    "name": "theme_settings.logo.label",
    "fields": [
      {
        "type": "image_picker",
        "id": "logo_dark",
        "label": "theme_settings.logo_dark.label"
      },
      {
        "type": "image_picker",
        "id": "logo_light",
        "label": "theme_settings.logo_light.label"
      },
      {
        "type": "image_picker",
        "id": "favicon",
        "label": "theme_settings.favicon.label",
        "image_size": "128x128"
      }
    ]
  },
  {
    "name": "theme_settings.colors.label",
    "fields": [
      {
        "type": "color_picker",
        "id": "base_color",
        "label": "theme_settings.base_color.label",
        "default": "#2563eb"
      }
    ]
  },
  {
    "name": "theme_settings.social_media.label",
    "fields": [
      {
        "type": "text",
        "id": "social_link_facebook",
        "label": "theme_settings.social_media_links.facebook.label",
        "placeholder": "https://facebook.com/rentmave"
      },
      {
        "type": "text",
        "id": "social_link_instagram",
        "label": "theme_settings.social_media_links.instagram.label",
        "placeholder": "https://instagram.com/rentmave"
      },
      {
        "type": "text",
        "id": "social_link_x",
        "label": "theme_settings.social_media_links.x.label",
        "placeholder": "https://x.com/rentmave"
      },
      {
        "type": "text",
        "id": "social_link_linkedin",
        "label": "theme_settings.social_media_links.linkedin.label",
        "placeholder": "https://www.linkedin.com/company/rentmave"
      },
      {
        "type": "text",
        "id": "social_link_youtube",
        "label": "theme_settings.social_media_links.youtube.label",
        "placeholder": "https://www.youtube.com/rentmave"
      },
      {
        "type": "text",
        "id": "social_link_vimeo",
        "label": "theme_settings.social_media_links.vimeo.label",
        "placeholder": "https://vimeo.com/vimeo"
      },
      {
        "type": "text",
        "id": "social_link_tiktok",
        "label": "theme_settings.social_media_links.tiktok.label",
        "placeholder": "https://tiktok.com/@rentmave"
      },
      {
        "type": "text",
        "id": "social_link_snapchat",
        "label": "theme_settings.social_media_links.snapchat.label",
        "placeholder": "https://www.snapchat.com/add/rentmave"
      },
      {
        "type": "text",
        "id": "social_link_pinterest",
        "label": "theme_settings.social_media_links.pinterest.label",
        "placeholder": "https://pinterest.com/rentmave"
      },
      {
        "type": "text",
        "id": "social_link_tumblr",
        "label": "theme_settings.social_media_links.tumblr.label",
        "placeholder": "https://rentmave.tumblr.com"
      },
      {
        "type": "text",
        "id": "social_link_telegram",
        "label": "theme_settings.social_media_links.telegram.label",
        "placeholder": "https://t.me/rentmave"
      }
    ]
  },
  {
    "name": "theme_settings.pages.label",
    "fields": [
      {
        "type": "image_picker",
        "id": "pages_background_image",
        "label": "theme_settings.pages_background_image.label",
        "image_size": "1900x600"
      }
    ]
  },
  {
    "name": "theme_settings.footer.label",
    "fields": [
      {
        "type": "textarea",
        "id": "footer_about_text",
        "label": "theme_settings.footer_about_text.label"
      }
    ]
  },
  {
    "name": "theme_settings.extra.label",
    "fields": [
      {
        "type": "radio",
        "id": "enable_cookie_notice",
        "boolean": true,
        "label": "theme_settings.enable_cookie_notice.label"
      }
    ]
  },
  {
    "name": "theme_settings.facility_icons.label",
    "fields": [
      {
        "type": "select",
        "id": "icon_weight",
        "label": "theme_settings.icon_weight.label",
        "helper_text": "theme_settings.icon_weight.helper_text",
        "default": "regular",
        "options": {
          "thin": "theme_settings.icon_weight.options.thin",
          "light": "theme_settings.icon_weight.options.light",
          "regular": "theme_settings.icon_weight.options.regular",
          "bold": "theme_settings.icon_weight.options.bold",
          "fill": "theme_settings.icon_weight.options.fill",
          "duotone": "theme_settings.icon_weight.options.duotone"
        }
      }
    ]
  },
  {
    "name": "theme_settings.custom_css.label",
    "fields": [
      {
        "type": "code_editor",
        "id": "custom_css",
        "label": "theme_settings.custom_css.label",
        "helper_text": "theme_settings.custom_css.helper_text"
      }
    ]
  }
]

Reading settings in a template

<body style="--brand: {{ settings.base_color | default: '#4f46e5' }}">
  {% if settings.show_footer %}
    <footer>…</footer>
  {% endif %}

On install, each field's default is seeded as the stored value, so settings.<id> resolves from day one: a freshly installed theme never sees an undeclared key. Liquid has no ?? operator; reach for the standard default filter when you want an inline fallback anyway (e.g. before a host has changed a color picker away from a value that happens to be empty).

Where values live

• You declare fields in config/settings_schema.json.
• Hosts edit values on the theme settings page; each field's default is seeded on install, and values are stored per install.
• Templates read them from the settings global, e.g. {{ settings.base_color }}.

There is no theme_setting() function; settings are plain keys on the settings global. settings is site-wide, available on every page; a section's own per-instance fields arrive as a different variable, block_settings, only inside that section's template. See Templating → settings, general_settings, and block_settings.

A field's label (and a helper_text, if it has one) can be a translation key instead of literal text, resolved for the host from an optional lang/<code>.admin.json catalog rather than your guest-facing locales/<code>.json. See Templating → locales and routing.