Your company here ā€” click to reach over 10,000 unique daily visitors

aerc-stylesets - Man Page

styleset file specification for aerc(1)


aerc uses a simple configuration syntax to configure the styleset for its ui.

Styleset Configuration

The styleset is described as <object>.<attribute> = <value> pairs.

For example, in the line below, the foreground color of the style object msglist_unread is set to cornflowerblue

msglist_unread.fg = cornflowerblue

The configuration also allows wildcard matching of the keys to configure multiple style objects at a time.


The following options are available to be modified for each of the style objects.

<object>.fg = <color>

The foreground color of the style object is set.

<object>.bg = <color>

The background color of the style object is set.

<object>.bold = true|false|toggle

The bold attribute of the style object is set/unset.

<object>.blink = true|false|toggle

The blink attribute of the style object is set/unset. The terminal needs to support blinking text.

<object>.underline = true|false|toggle

The underline attribute of the style object is set/unset. The terminal needs to support underline text.

<object>.italic = true|false|toggle

The italic attribute of the style object is set/unset. The terminal needs to support italic text.

<object>.dim = true|false|toggle

The dim attribute of the style object is set/unset. The terminal needs to support half-bright text.

<object>.reverse = true|false|toggle

Reverses the color of the style object. Exchanges the foreground and background colors.

If the value is false, it doesn't change anything.

<object>.normal = true

All the attributes of the style object are unset.

The value doesn't matter.

<object>.default = true

Set the style object to the default style of the context. Usually based on the terminal.

The value doesn't matter.

Style Objects

The style objects represent the various ui elements or ui instances for styling.

Style ObjectDescription
defaultThe default style object used for normal ui elements while not using specialized configuration.
errorThe style used to show errors.
warningThe style used when showing warnings.
successThe style used for success messages.
titleThe style object used to style titles in ui elements.
headerThe style object used to style headers in ui elements.
statusline_defaultThe default style applied to the statusline.
statusline_errorThe style used for error messages in statusline.
statusline_successThe style used for success messages in statusline.
msglist_defaultThe default style for messages in a message list.
msglist_unreadUnread messages in a message list.
msglist_readRead messages in a message list.
msglist_flaggedThe messages with the flagged flag.
msglist_deletedThe messages marked as deleted.
msglist_markedThe messages with the marked flag.
msglist_resultThe messages which match the current search.
msglist_answeredThe messages marked as answered.
msglist_gutterThe message list gutter.
msglist_pillThe message list pill.
msglist_thread_foldedVisible messages that have folded thread children.
dirlist_defaultThe default style for directories in the directory list.
dirlist_unreadThe style used for directories with unread messages
dirlist_recentThe style used for directories with recent messages
part_switcherBackground for the part switcher in the message viewer.
part_filenameAttachment file name in the part switcher.
part_mimetypeAttachment/part MIME type in the part switcher.
completion_defaultThe default style for the completion engine.
completion_gutterThe completion gutter.
completion_pillThe completion pill.
tabThe style for the tab bar.
stackThe style for ui stack element.
spinnerThe style for the loading spinner.
borderThe style used to draw borders (only the bg color is used unless you customize border-char-vertical and/or border-char-horizontal in aerc.conf).
selector_defaultThe default style for the selector ui element.
selector_focusedThe focused item in a selector ui element.
selector_chooserThe item chooser in a selector ui element.

These next style objects only affect the built-in colorize filter and must be declared under a [viewer] section of the styleset file.

Style ObjectDescription
headerRFC-822-like header names.
signatureEmail signatures.
diff_metaPatch diff meta lines.
diff_chunkPatch diff chunks.
diff_chunk_funcPatch diff chunk function names.
diff_addPatch diff added lines.
diff_delPatch diff deleted lines.
quote_1First level quoted text.
quote_2Second level quoted text.
quote_3Third level quoted text.
quote_4Fourth level quoted text.
quote_xAbove fourth level quoted text.

User defined styles can be used to style arbitrary strings in go-templates (see .Style in aerc-templates(7)). User styles must be defined in the [user] ini section. Styles can be referenced by their name (e.g. red.fg is named "red").



User styles are layered with other styles applied to the context in which they are rendered. The user style colors (fg and/or bg) will only be effective if the context style does not define any. Other boolean attributes will be merged with the underlying style boolean attributes.

For example, if the context style is:

fg=red bold

And the inline style is:

fg=yellow italic underline

The effective style will be:

fg=red bold italic underline

Fnmatch Style Wildcard Matching

The styleset configuration can be made simpler by using the fnmatch style wildcard matching for the style object.

The special characters used in the fnmatch wildcards are:

*Matches everything
?Matches any single character

For example, the following wildcards can be made using this syntax.

*.fg = blueSet the foreground color of all style objects to blue.
*list.bg = hotpinkSet the background color of all style objects that end in list to hotpink.

Note that the statements in a given styleset are parsed in the order in which they are written. That means that with the following styleset:

  msglist_marked.fg = pink
  msglist_*.fg = white

The msglist_marked.fg attribute will be set to white.

Selected Modifier

The selected modifier can be applied to any style object. The style provided for the selected modifier is applied on top of the style object it corresponds to.

If you would like to make sure message that are flagged as read in the msglist appear in yellow foreground and black background. You can specify that with this:

msglist_default.selected.fg = yellow

msglist_default.selected.bg = black

If we specify the global style selected modifier using fnmatch as below:

*.selected.reverse = toggle

This toggles the reverse switch for selected version of all the style objects.

selected objects inherit from all attributes of their non-selected counterparts. selected statements are parsed after non-selected ones and effectively override the attributes of the non-selected style object.

Layered Styles

Some styles, (currently the msglist_* and dirlist_* ones) are applied in layers. If a style differs from the base (in this case *list_default) then that style applies, unless overridden by a higher layer. If fg and bg colors are not defined explicitly (or defined to the default color) they will be considered as "transparent" and the colors from the lower layer will be used instead.

The order that msglist_* styles are applied in is, from first to last:

  1. msglist_default
  2. msglist_unread
  3. msglist_read
  4. msglist_answered
  5. msglist_flagged
  6. msglist_deleted
  7. msglist_result
  8. msglist_thread_folded
  9. msglist_marked

So, the marked style will override all other msglist styles.

The order for dirlist_* styles is:

  1. dirlist_default
  2. dirlist_unread
  3. dirlist_recent

Dynamic Message List Styles

All msglist_* styles can be defined for specific email header values. The syntax is as follows:

msglist_<name>.<header>,<header_value>.<attribute> = <attr_value>

If <header_value> starts with a tilde character ~, it will be interpreted as a regular expression.


  msglist*.X-Sourcehut-Patchset-Update,APPROVED.fg = green
  msglist*.X-Sourcehut-Patchset-Update,NEEDS_REVISION.fg = yellow
  msglist*.X-Sourcehut-Patchset-Update,REJECTED.fg = red
  "msglist_*.Subject,~^(\[[w-]+]\s*)?\[(RFC )?PATCH.fg" = #ffffaf
  "msglist_*.Subject,~^(\[[w-]+]\s*)?\[(RFC )?PATCH.selected.fg" = #ffffaf

When a dynamic style is matched to an email header, it will be used in priority compared to its non-dynamic counterpart. Provided the following styleset:

  msglist_marked.fg = blue
  msglist_*.Subject,~foobar.fg = red

An email with foobar it its subject will be colored in red all the time, since msglist_* also applies to msglist_marked.


The color values are set using the values accepted by the tcell library. The values can be one of the following.


The color is set as per the system or terminal default.

<Color name>

Any w3c approved color name is used to set colors for the style.

<Hex code>

Hexcode for a color can be used. The format must be #XXXXXX.

<Dec number>

Color based on the terminal palette index. Valid numbers are between 0 and 255.


Before parsing a styleset, it is first initialized with the following defaults:

  border.reverse = true

You can choose either to reset everything by starting your styleset with these two lines:


Or selectively override style object attributes.

See Also

aerc(1) aerc-config(5)


Originally created by Drew DeVault and maintained by Robin Jarry who is assisted by other open source contributors. For more information about aerc development, see https://sr.ht/~rjarry/aerc/.

Referenced By

aerc(1), aerc-config(5), aerc-templates(7).