Theme Customization
Appearance → Customize is generated for each theme. jekcms reads the active theme's theme.json, adds a set of controls that every theme gets, and shows the result as a tabbed panel with a live preview next to it.

Changes here do not modify theme files. Values are stored in the database under the theme slug, so a theme update does not delete them, and your settings are still there when you switch to another theme and back.
The customizer is a licensed feature. On a free install the screen is not available.
Where the panel comes from
A theme declares its tabs and fields under customizer.tabs in theme.json:
{
"customizer": {
"tabs": {
"branding": {
"label": { "tr": "Marka", "en": "Branding" },
"icon": "palette",
"fields": {
"accent": {
"type": "color",
"label": "Accent colour",
"default": "#2563eb",
"css_var": "--color-accent"
}
}
}
}
}
}
Each tab carries a label (a string, or a {tr, en} pair), an optional icon and description, and a fields map. Every theme that ships with jekcms declares its own set, typically branding, appearance, menu, homepage, single, footer and advanced.
A theme that declares no tabs gets a default set (branding, typography, layout and advanced), so the customizer is never empty.
Field types
| Type | Renders as | |---|---| | color | Colour picker with a hex box; gets an automatic dark-mode twin | | font | Font dropdown where every option is shown in its own typeface | | range (or number) | Slider with a live value readout, honouring min, max, step and unit | | toggle (or checkbox) | On/off switch | | select | Dropdown, from a list or a key→label map | | choice_cards | Radio cards with a small CSS mock-up of each option | | textarea | Multi-line text box | | code | Monospace box, language picks the flavour | | image | Text field with a preview and a link to the media library | | url, text | Single-line inputs |
An unknown type is shown as a plain text input instead of causing an error, so a typo in theme.json affects only one control, not the whole screen.
Beyond type, label and default, a field can carry help text, a placeholder, depends_on to show itself only when another field has a given value, optional to sit behind a "Customize" checkbox, and emit_saved_only so that nothing is written to the page until the user saves a value.
Reading a value in a template
<?php $layout = theme_option('menu.layout', 'classic'); ?>
The key is tab.field and the second argument is your fallback. An unsaved field, or a field saved as an empty string, returns that fallback. The "Theme default" option in the customizer works this way: an empty value means the theme's own value is used.
theme_option() is the only function you need for this. It is different from theme_setting(), which each theme defines in its own functions.php. theme_setting() reads the static settings block of theme.json, which holds defaults built into the theme that users cannot edit.
From a saved value to a CSS variable
In most cases you do not need to read values in PHP. A field that declares a css_var is printed automatically as a CSS custom property, and your stylesheet uses it.
<head>
…
<?php output_theme_customization_css(); ?>
</head>
Every shipped theme already calls this in its header template. It goes through the schema, takes every field with a css_var and formats the value by type: colours are checked against a hex pattern, ranges get their unit, and fonts become a full font stack. Then it prints one <style id="theme-customization"> block:
<style id="theme-customization">
:root {
--color-accent: #dc2626;
--font-heading: 'Fraunces', Georgia, serif;
--container-max: 1200px;
}
</style>
Your stylesheet then uses them:
.btn-primary { background: var(--color-accent); }
A css_var may also be an array of names, in which case all of them are written. This lets one control work in several themes that use different variable names for the same value. The function also calculates readable text colours for accent backgrounds, so --color-accent automatically gets a matching --color-accent-ink.
The same block contains the styles generated by the universal studios and, at the end, your Custom CSS, so your own rules override everything above them.
Dark mode
If a theme declares a dark-mode selector (the default is [data-theme="dark"]), every colour field with a css_var automatically gets a paired dark field. The customizer shows the two side by side; the light value goes into :root and the dark value goes into a block under the theme's dark selector, printed after the theme's own dark rules so it wins at equal specificity.
If the dark value is empty, nothing is written and the theme's own dark colours are used. A theme can set "dark_selector": "media" to key off prefers-color-scheme instead, or false to opt out of the whole mechanism.
Controls every theme gets
The core adds its own controls to every theme. They do not conflict with a theme's fields, because a control is added only when the theme has no field for the same setting. While a control is set to "Theme default" or left empty, it writes nothing.
Colours adds the eight colour roles that the theme does not offer itself: primary, secondary, text, muted text, background, surface, border, link - each with a dark twin. Typography adds heading and body fonts from a selection of about forty Google Fonts, heading weight, letter case, letter spacing and the article text column width. Branding gains separate logo-height sliders for the header and the footer.
In addition, there are the studios: the top bar and announcement strip, the main menu design, buttons, header and footer colours, card design, the share bar, comment section designs, the sidebar, the post page and the archive. Each studio is a core module that adds its fields to the relevant tab, so the studios work the same way in every theme.
Sections, order and device visibility
Themes declare their pages as section cards that you can reorder (hero, latest posts, category strips and others) inside the customizer's page tabs. Drag a card to move it, switch it off, pick a variant, or open its gear for per-section settings.
The first setting in every gear panel is device visibility: all devices, desktop only, or mobile only. It is implemented with CSS media queries, so hiding a section on phones does not disturb the layout on the devices where it still appears.
Live preview
The preview button next to each section group opens your real site with your unsaved changes applied. Only your own admin session sees the draft; visitors keep the saved layout until you press Save. Desktop, tablet and mobile width buttons let you check a device-visibility rule on each screen size before you save it.
Custom CSS and custom HTML
The Advanced tab of every shipped theme holds three code fields.
Custom CSS is added at the end of the customization style block. Use it for individual overrides that should survive the next theme update. Extra <head> HTML is inserted just before </head>, for verification meta tags, analytics snippets or a font you load yourself. Extra footer HTML goes in before </body>, for chat widgets and late-loading scripts.
The two HTML fields are printed exactly as you type them, without sanitising or validation. Paste only code you understand, because a broken tag here breaks every page on the site.