---
title: Preferences
---

import { Callout } from 'fumadocs-ui/components/callout';

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.

```json title="Checkbox Example"
{
  "property": "mod.mymod.enable_dark_mode",
  "label": "Enable dark mode",
  "type": "checkbox"
}
```

#### Type: `dropdown`

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

```json title="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.

```json title="String Example"
{
  "property": "mod.mymod.tab_padding",
  "label": "Set tab padding",
  "type": "string"
}
```

### Field: `options` - Options (only for `type`: `dropdown`)

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.

```json
  "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.

```json title="Example"
{
  "label": "Green",
  "value": "green" // valid string
}
```

```json title="Invalid Example" {3}
{
  "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:

```json title="Disabled on MacOS" {2}
{
  "disabledOn": ["macos"] // disables the preference for MacOS
}
```

```json title="Disabled on Windows and Linux" {2}
{
  "disabledOn": ["windows", "linux"] // disables the preference for Windows and Linux
}
```

```json title="Disabled on all OS" {2}
{
  "disabledOn": ["windows", "linux", "macos"] // disables the preference entirely
}
```

### Field: `placeholder` - Placeholder (optional) (only for `type`: `dropdown` and `string`)

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:

```json
[
  {
    "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:

```json
{
  "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:

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

You can also have negative conditions

```css {1}
@media not (-moz-bool-pref: "mod.mymod.enable_dark_mode");
```

### Dropdown Preferences

<Callout type="warn" title="Attention">
  `property` fields defined in `preferences.json` using the `"dropdown"` type will have one key difference when used in your mod's CSS: <strong>dots (`.`) in the `property` name are replaced with hyphens (`-`)</strong>.
  <br/><br/>
  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.
</Callout>

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:

```json
{
  "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:

```css {2,8,14}
/* 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:

```json
[
  {
    "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:

```css
/* 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.

<Callout type="warn" title="Attention">
  `property` fields defined in `preferences.json` using the `"string"` type will have one key difference when used in your mod's CSS: <strong>dots (`.`) in the `property` name are replaced with hyphens (`-`)</strong>.
  <br/><br/>
  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.
</Callout>

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

```json
{
  "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:

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