Preferences

The preferences.json file allows mod developers to define custom preferences that control the behavior and appearance of mods in the Zen Browser. Each preference is defined with a property, a label, a type, and optionally options (for dropdown preferences), defaultValue, placeholder (to configure preference placeholder) and disabledOn (to disable property on selected OS). The preferences.json file contains a list of these preference objects at its root.

Preferences fields

Field: `property` - Property name

The property field is a string that should follow Firefox's preference naming schema, similar to about:config entries. The property name can be any valid string that aligns with this schema.

For example: mod.mymod.background_color

Field: `label` - Label

The label field is the description that will be visible to users in the Zen Mods settings page. This field accepts a string and allows white space.

For example: Changes the background color

Field: `type` - Preference type

Property	Type	Accepted Values
`checkbox`	Boolean	`true`, `false`
`dropdown`	Array[Options]	The `value` of an option must be a string (`"blue"`) or an integer (`1`)
`string`	String	The `value` of an option must be a string (`"blue"`) (a valid CSS property value)

Type: `checkbox`

The checkbox type allows a togglable input to enable or disable a property.

Checkbox Example

{
  "property": "mod.mymod.enable_dark_mode",
  "label": "Enable dark mode",
  "type": "checkbox"
}

The dropdown type allows to select a single choice on multiple options.

Dropdown Example

{
  "property": "mod.mymod.background_color",
  "label": "Background color",
  "type": "dropdown",
  "options": [
    {
      "label": "Green",
      "value": "green"
    },
    {
      "label": "Blue",
      "value": "blue"
    }
  ]
}

Type: `string`

The string type is a text input that allows to insert valid css values without being a selection.

String Example

{
  "property": "mod.mymod.tab_padding",
  "label": "Set tab padding",
  "type": "string"
}

The options field is an array of option objects, only available for the dropdown type. This field must be an array containing one or more option objects.

  "options": [
    {
      "label": "Light",
      "value": "light"
    },
    {
      "label": "Dark",
      "value": "dark"
    }
  ]

Each option object defines a possible value for the dropdown menu. It contains two fields: label and value.

The label is the description that will be displayed in the dropdown menu. This field accepts a string and allows white space.
The value field contains the value that will be assigned as a CSS property. Only string or int values are valid. Strings may not contain white space or special characters.

Example

{
  "label": "Green",
  "value": "green" // valid string
}

Invalid Example

{
  "label": "Invalid option",
  "value": [] // invalid, only string/int are allowed
}

Field: `defaultValue` - Default Value (optional)

The defaultValue field is an optional field that allows the preference to have a pre-selected value. This field accepts a value based on the preference type:

Type	Default Value Type	Accepted Values
`checkbox`	Boolean	`true`, `false`
`dropdown`	Array[Options]	Any `value` contained in the options array.
`string`	String	The `value` of an option must be a string (`"blue"`) (a valid CSS property value)

Field: `disabledOn` - Disabled On (optional)

Some CSS modifications may not function properly on all operating systems. You can use the property disabledOn to specify on which operating systems the preference should be available.

This field accepts an array of the following values: macos, linux or/and windows.

For example:

Disabled on MacOS

{
  "disabledOn": ["macos"] // disables the preference for MacOS
}

Disabled on Windows and Linux

{
  "disabledOn": ["windows", "linux"] // disables the preference for Windows and Linux
}

Disabled on all OS

{
  "disabledOn": ["windows", "linux", "macos"] // disables the preference entirely
}

The placeholder field is an optional field that allows to change the placeholder value for the preference. This field accepts a string and allows white space.

For example: e.g: 10px

See Full Example

Below is a full example of what a preferences.json file might look like with multiple preference objects in its root. Each object represents a preference defined for a mod:

[
  {
    "property": "mod.mymod.enable_dark_mode",
    "label": "Enable dark mode",
    "type": "checkbox",
    "defaultValue": true
  },
  {
    "property": "mod.mymod.background_color",
    "label": "Background color",
    "type": "dropdown",
    "placeholder": "Select a color",
    "defaultValue": "green",
    "options": [
      {
        "label": "Green",
        "value": "green"
      },
      {
        "label": "Blue",
        "value": "blue"
      }
    ]
  },
  {
    "property": "mod.mymod.show_bookmarks_bar",
    "label": "Show bookmarks bar",
    "type": "string",
    "disabledOn": ["macos"]
  }
]

In this example:

The preferences.json file contains a list of three preference objects.
Each object defines a property, label, and type.
Optionally, each object defines either a defaultValue, disabledOn or placeholder.
Dropdown preferences have to include an options field, with each option having a label and a value.

Using preferences in the mod's CSS

Once you have defined your preferences in the preferences.json file, you can use them in your mod’s CSS to modify the appearance or behavior based on the user’s selections.

Checkbox Preferences

Checkbox preferences can be detected in your CSS using the -moz-bool-pref media query, which evaluates the boolean value (true or false) of a checkbox preference.

For example, if you have a preference to enable dark mode in your mod:

{
  "property": "mod.mymod.enable_dark_mode",
  "label": "Enable dark mode",
  "type": "checkbox"
}

You can use the following CSS to change the background color when the dark mode preference is enabled:

@media (-moz-bool-pref: "mod.mymod.enable_dark_mode") {
  body {
    background-color: #000;
    color: #fff;
  }
}

You can also have negative conditions

@media not (-moz-bool-pref: "mod.mymod.enable_dark_mode");

Attention

property fields defined in preferences.json using the "dropdown" type will have one key difference when used in your mod's CSS: dots (.) in the property name are replaced with hyphens (-).

E.g. mod.mymod.background_color becomes mod-mymod-background_color in the CSS file. This transformation ensures that the property can be used as an attribute selector or inside a media query.

For dropdown preferences, you can detect the selected value using the :has(){:css} CSS pseudo-class, which applies styles based on the selected attribute and value in the DOM.

For example, if you have a preference to select the background color from a dropdown menu:

{
  "property": "mod.mymod.background_color",
  "label": "Background color",
  "type": "dropdown",
  "options": [
    {
      "label": "Green",
      "value": "green"
    },
    {
      "label": "Blue",
      "value": "blue"
    }
  ]
}

You can use the following CSS to change the background color based on the selected value:

/* Green background */
body:has(#mod-mymod[mod-mymod-background_color="green"]) {
  background-color: #008000;
  color: #000;
}
 
/* Blue background */
body:has(#mod-mymod[mod-mymod-background_color="blue"]) {
  background-color: #0000ff;
  color: #fff;
}

In this example:

The background color and text color change based on the value selected in the background_color dropdown.
The selector body:has(#mod-mymod[background_color="value"]){:css} checks the background_color attribute and applies the relevant styles based on the selected option.

See Full Example

Suppose your preferences.json file includes these two preferences:

[
  {
    "property": "mod.mymod.enable_dark_mode",
    "label": "Enable dark mode",
    "type": "checkbox"
  },
  {
    "property": "mod.mymod.background_color",
    "label": "Background color",
    "type": "dropdown",
    "options": [
      {
        "label": "Green",
        "value": "green"
      },
      {
        "label": "Blue",
        "value": "blue"
      }
    ]
  }
]

You can combine the CSS like this:

/* Checkbox for dark mode */
@media (-moz-bool-pref: "mod.mymod.enable_dark_mode") {
  body {
    background-color: #000;
    color: #fff;
  }
}
 
/* Dropdown for background color selection */
body:has(#mod-mymod[mod-mymod-background_color="green"]) {
  background-color: #008000;
  color: #000;
}
 
body:has(#mod-mymod[mod-mymod-background_color="blue"]) {
  background-color: #0000ff;
  color: #fff;
}

This allows users to:

Toggle dark mode on/off using the checkbox.
Select a background color from the dropdown, which dynamically changes the background and text colors based on the user's choice.

String Preferences

String preferences can be detected in your CSS using the var(--property) operator. The preference property is saved at :root level.

Attention

property fields defined in preferences.json using the "string" type will have one key difference when used in your mod's CSS: dots (.) in the property name are replaced with hyphens (-).

E.g. mod.mymod.background_color becomes mod-mymod-background_color in the CSS file. This transformation ensures that the property can be used as an attribute selector or inside a media query.

For example, if you have a preference to enable dark mode in your mod:

{
  "property": "mod.mymod.background_color",
  "label": "Background color",
  "type": "string"
}

You can use the following CSS to change the background color when the dark mode preference is enabled:

.myClass {
  background-color: var(--mod-mymod-background_color);
}

Preferences

On this page