How To Use Mod Preferences For Local Testing ?

[rfNeoN]

Hi,
i was working on a mod and my css file it working but when i tried to use preferences it just break, i don't know how to set it up for local testing and it just doesn't work and cant find a solution for it in the documentation about how to structure it.

any help is appreciated.

[Lopesnextgen]

Hey Raouf,

For local testing, the important bit is that Zen does not load preferences.json just because the file exists next to your CSS. The mod also has to be registered as an installed mod, and that installed mod entry needs a preferences field.

A minimal local setup should look like this inside your Zen profile folder:

<profile>/
  zen-themes.json
  chrome/
    zen-themes/
      local-test-mod/
        chrome.css
        preferences.json

You can find the profile folder from:

about:support -> Profile Folder -> Open Folder

Then create/edit:

zen-themes.json

Example:

{
  "local-test-mod": {
    "id": "local-test-mod",
    "name": "Local Test Mod",
    "description": "Testing local CSS preferences",
    "author": "rfNeoN",
    "version": "1.0.0",
    "style": "local",
    "readme": "local",
    "preferences": "local",
    "enabled": true
  }
}

The preferences value does not need to be a real URL for manual local testing, but it does need to exist and be truthy. Zen’s mod loader checks for both:

• <profile>/chrome/zen-themes/<mod-id>/preferences.json
• mod.preferences in zen-themes.json

If either one is missing, the preferences list will be treated as empty.

Minimal preferences.json

Make sure the root is an array, not an object:

[
  {
    "property": "theme.local_test.enabled",
    "label": "Enable test style",
    "type": "checkbox",
    "defaultValue": true
  },
  {
    "property": "theme.local_test.color",
    "label": "Accent color",
    "type": "dropdown",
    "defaultValue": "red",
    "options": [
      {
        "label": "Red",
        "value": "red"
      },
      {
        "label": "Blue",
        "value": "blue"
      }
    ]
  },
  {
    "property": "theme.local_test.radius",
    "label": "Border radius",
    "type": "string",
    "defaultValue": "10px"
  }
]

Using those preferences in chrome.css

For a checkbox, use -moz-pref:

@media (-moz-pref("theme.local_test.enabled")) {
  #navigator-toolbox {
    outline: 2px solid red !important;
  }
}

For a dropdown, Zen exposes the selected value on a hidden DOM element. The element id is based on the mod name:

Local Test Mod -> #theme-Local-Test-Mod

Dots in the preference name become hyphens:

theme.local_test.color -> theme-local_test-color

So the CSS would be:

:root:has(#theme-Local-Test-Mod[theme-local_test-color="red"]) {
  #navigator-toolbox {
    background: color-mix(in srgb, red 20%, transparent) !important;
  }
}

:root:has(#theme-Local-Test-Mod[theme-local_test-color="blue"]) {
  #navigator-toolbox {
    background: color-mix(in srgb, blue 20%, transparent) !important;
  }
}

For a string preference, Zen exposes it as a CSS variable on :root:

theme.local_test.radius -> --theme-local_test-radius

Example:

#navigator-toolbox {
  border-radius: var(--theme-local_test-radius) !important;
}

Common things that break it

• preferences.json is an object instead of an array.
• The mod entry in zen-themes.json does not have a preferences field.
• The folder name does not match the mod id.
• The selector id does not match the sanitized mod name.
• You used dots in the CSS attribute/variable name instead of replacing them with hyphens.
• The mod is disabled in zen-themes.json.
• Zen has not reloaded the generated mods stylesheet yet.

After changing files, restart Zen or disable/enable the mod from the Zen Mods settings page. If the CSS still works but the preferences do not show up, check the Browser Console for a line like:

[ZenMods]: Error reading mod preferences

That usually means the JSON is invalid or the structure is not what Zen expects.

References:

• Zen preferences docs: https://docs.zen-browser.app/themes-store/themes-marketplace-preferences
• Zen mod loader source: https://github.com/zen-browser/desktop/blob/dev/src/zen/mods/ZenMods.mjs
• Example mod with preferences: https://github.com/zen-browser/theme-store/tree/main/themes/74c755b3-41a5-4f78-83cb-cd1e1e076bb6