The preferences.json
file allows theme developers to define custom preferences that control the behavior and appearance of themes 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: theme.mytheme.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.
Type: dropdown
The dropdown
type allows to select a single choice on multiple options.
Type: string
The string
type is a text input that allows to insert valid css values without being a selection.
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.
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. Onlystring
orint
values are valid. Strings may not contain white space or special characters.
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:
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 theme:
In this example:
- The
preferences.json
file contains a list of three preference objects. - Each object defines a
property
,label
, andtype
. - Optionally, each object defines either a
defaultValue
,disabledOn
orplaceholder
. - Dropdown preferences have to include an
options
field, with each option having alabel
and avalue
.
Using preferences in the theme’s CSS
Once you have defined your preferences in the preferences.json
file, you can use them in your theme’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 theme:
You can use the following CSS to change the background color when the dark mode preference is enabled:
You can also have negative conditions
Dropdown Preferences
Attention
property
fields defined inpreferences.json
using the"dropdown"
type will have one key difference when used in your themes CSS: dots (.
) in theproperty
name are replaced with hyphens (-
).E.g.
theme.mytheme.background_color
becomestheme-mytheme-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 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:
You can use the following CSS to change the background color based on the selected value:
In this example:
- The background color and text color change based on the value selected in the
background_color
dropdown. - The selector
body:has(#theme-mytheme[background_color="value"])
checks thebackground_color
attribute and applies the relevant styles based on the selected option.
See Full Example
Suppose your preferences.json
file includes these two preferences:
You can combine the CSS like this:
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 inpreferences.json
using the"string"
type will have one key difference when used in your themes CSS: dots (.
) in theproperty
name are replaced with hyphens (-
).E.g.
theme.mytheme.background_color
becomestheme-mytheme-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 theme:
You can use the following CSS to change the background color when the dark mode preference is enabled: