Skip to content

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:

PropertyMeaning
idThe setting key. Your templates read it as settings.<id>.
typeInput type (see below).
labelLabel shown in the settings form.
defaultDefault value before the host changes anything.
fieldsFor 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 ​

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 ​

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

Image and video fields ​

image_picker and video_picker let a host choose a file from their media library, or upload one on the spot. Your template never sees a media id: the value arrives as a finished, hosted URL, and it stays blank until the host picks something, so a plain != blank guard is all you need.

TypeThe host picksYour template receives
image_pickerOne imageA URL string
image_picker with "multiple": trueSeveral images, in the order they arranged themA list of URL strings
video_pickerOne MP4 or WebM videoA URL string

Both types work in config/settings_schema.json and in config/blocks.json, including inside a repeater.

Background video with a still underneath ​

video_picker accepts MP4 and WebM only, the two formats every current browser plays. A host can upload a video of up to 100 MB (images are capped at 10 MB), but a background loop should weigh far less than that: every guest downloads it, so aim for a short, silent clip of a few megabytes. Pair it with an image_picker so the section has something to show before the video arrives:

json
{
  "id": "hero",
  "label": "theme_blocks.hero.label",
  "fields": [
    {
      "type": "image_picker",
      "id": "background_image",
      "label": "theme_blocks.hero.fields.background_image.label",
      "image_size": "1920x1080"
    },
    {
      "type": "video_picker",
      "id": "background_video",
      "label": "theme_blocks.hero.fields.background_video.label",
      "helper_text": "theme_blocks.hero.fields.background_video.helper_text"
    }
  ]
}
liquid
{# sections/hero.liquid #}
<section class="hero">
  {% if block_settings.background_image != blank %}
    <img class="hero__media" src="{{ block_settings.background_image }}" alt="" fetchpriority="high">
  {% endif %}
  {% if block_settings.background_video != blank %}
    <video class="hero__media hero__video" data-src="{{ block_settings.background_video }}"
           muted loop playsinline preload="none" aria-hidden="true" tabindex="-1"></video>
  {% endif %}
  <h1>{{ block_settings.heading }}</h1>
</section>

Print the still as a real <img> and leave src off the <video>. The image is then the only media the page loads up front, so the largest paint is fast and the page carries a real image rather than a CSS background. A few lines of script add the video afterwards and reveal it once it is playing:

js
const video = document.querySelector('.hero__video')
const reducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)')

if (video && !reducedMotion.matches) {
  video.addEventListener('playing', () => video.classList.add('is-playing'))
  video.src = video.dataset.src
  video.play().catch(() => {})
}
css
.hero { position: relative; overflow: hidden; }
.hero__media { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
.hero__video { opacity: 0; transition: opacity 0.7s ease; }
.hero__video.is-playing { opacity: 1; }

Guests who ask for reduced motion never download the video, and when a browser refuses to autoplay it (low-power mode, data saver) the still stays in place. A host who sets only the image gets a still section; one who sets only the video gets an empty background until it plays, so say in the field's helper_text that the two belong together.

© Stayblox — Developer Platform