4.10 Option for mode line presentation

Brief: Control the style of the mode lines.

Symbol: modus-themes-mode-line (‘choice’ type, list of properties)

Possible values, which can be expressed as a list of combinations of box effect, color, and border visibility:

The default (a nil value or an empty list) is a two-dimensional rectangle with a border around it. The active and the inactive mode lines use different shades of grayscale values for the background, foreground, border.

The 3d property applies a three-dimensional effect to the active mode line. The inactive mode lines remain two-dimensional and are toned down a bit, relative to the default style.

The moody property optimizes the mode line for use with the library of the same name (hereinafter referred to as ’Moody’). In practice, it removes the box effect and replaces it with underline and overline properties. It also tones down the inactive mode lines. Despite its intended purpose, this option can also be used without the Moody library (please consult the themes’ manual on this point for more details). If both 3d and moody properties are set, the latter takes precedence.

The borderless property removes the color of the borders. It does not actually remove the borders, but only makes their color the same as the background, effectively creating some padding.

The accented property ensures that the active mode line uses a colored background instead of the standard shade of gray.

A positive integer (natural number or natnum) applies a padding effect of NATNUM pixels at the boundaries of the mode lines. The default value is 1 and does not need to be specified explicitly. The padding has no effect when the moody property is also used, because Moody already applies its own tweaks. To ensure that the underline is placed at the bottom of the mode line, set x-underline-at-descent-line to non-nil (this is not needed when the borderless property is also set). For users on Emacs 29, the x-use-underline-position-properties variable must also be set to nil.

The padding can also be expressed as a cons cell in the form of ‘(padding . NATNUM)’ or ‘(padding NATNUM)’ where the key is constant and NATNUM is the desired natural number.

A floating point applies an adjusted height to the mode line’s text as a multiple of the main font size. The default rate is 1.0 and does not need to be specified. Apart from a floating point, the height may also be expressed as a cons cell in the form of ‘(height . FLOAT)’ or ‘(height FLOAT)’ where the key is constant and the FLOAT is the desired number.

Combinations of any of those properties are expressed as a list, like in these examples:

(accented)
(borderless 3d)
(moody accented borderless)

Same as above, using the padding and height as an example (these all yield the same result):

(accented borderless 4 0.9)
(accented borderless (padding . 4) (height . 0.9))
(accented borderless (padding 4) (height 0.9))

The order in which the properties are set is not significant.

In user configuration files the form may look like this:

(setq modus-themes-mode-line '(borderless accented))

Note that Moody does not expose any faces that the themes could style directly. Instead it re-purposes existing ones to render its tabs and ribbons. As such, there may be cases where the contrast ratio falls below the 7:1 target that the themes conform with (WCAG AAA). To hedge against this, we configure a fallback foreground for the moody property, which will come into effect when the background of the mode line changes to something less accessible, such as Moody ribbons (read the doc string of set-face-attribute, specifically :distant-foreground). This fallback is activated when Emacs determines that the background and foreground of the given construct are too close to each other in terms of color distance. In practice, users will need to experiment with the variable face-near-same-color-threshold to trigger the effect. We find that a value of ‘45000’ shall suffice, contrary to the default ‘30000’. Though for the combinations that involve the accented and moody properties, as mentioned above, that should be raised up to ‘70000’. Do not set it too high, because it has the adverse effect of always overriding the default colors (which have been carefully designed to be highly accessible).

Furthermore, because Moody expects an underline and overline instead of a box style, it is strongly advised to set x-underline-at-descent-line to a non-nil value.

Finally, note that various packages which heavily modify the mode line, such as ‘doom-modeline’, ‘nano-modeline’, ‘powerline’, ‘spaceline’ may not look as intended with all possible combinations of this user option.