AERC-STYLESETS(7)

🦋 AERC-STYLESETS(7) 🦋

bestie, welcome to the aerc-stylesets page from the Miscellaneous Information Manual — it's the styleset file spec for aerc(1), and we're gonna make it cute while keeping every single fact intact 💖

🌸 NAME 🌸

aerc-stylesets — styleset file specification for aerc(1).

✨ SYNOPSIS ✨

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

🎀 STYLESET CONFIGURATION 🎀

the styleset is described as <object>.<attribute> = <value> pairs. yes, that's the whole vibe: object, dot, attribute, equals, value 💅

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. so you can style a whole little squad of objects without typing every single key, periodt ✨

🔥 ATTRIBUTES 🔥

the following options are available to be modified for each of the style objects. every single one is here, no skipping:

• <object>.fg = <color> — sets the foreground color of the style object.
• <object>.bg = <color> — sets the background color of the style object.
• <object>.bold = true|false|toggle — sets/unset the bold attribute of the style object.
• <object>.blink = true|false|toggle — sets/unset the blink attribute of the style object. your terminal needs to support blinking text, bestie.
• <object>.underline = true|false|toggle — sets/unset the underline attribute of the style object. your terminal needs to support underline text.
• <object>.italic = true|false|toggle — sets/unset the italic attribute of the style object. your terminal needs to support italic text.
• <object>.dim = true|false|toggle — sets/unset the dim attribute of the style object. your 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 — sets 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. that's the whole section: these are the things you point your style keys at, iykyk 💜

okay so here's the full roster of style objects, bestie — this is the whole cast of characters, no skips, no "you'll figure it out" 💅

• default — the default style object, the one doing all the heavy lifting for normal ui elements whenever you haven't set up something specialized. the main character of fallbacks 👑
• error — the style used to show errors 🚨
• warning — the style used when showing warnings ⚠️
• success — the style used for success messages ✨
• title — the style object used to style titles in ui elements 🎀
• header — the style object used to style headers in ui elements 🌸
• realname — the style object used to style real name(s) in the email fields in the header section of the message viewer 🫶
• email — the style object used to style email(s) in the email fields in the header section of the message viewer 💌
• subject — the style object used to style subject in the header section of the message viewer ⭐
• date — the style object used to style date in the header section of the message viewer 🗓️
• statusline_default — the default style applied to the statusline 💫
• statusline_error — the style used for error messages in statusline 😭
• statusline_success — the style used for success messages in statusline 🌈
• msglist_default — the default style for messages in a message list 📬
• msglist_unread — unread messages in a message list 🔥
• msglist_read — read messages in a message list 💀
• msglist_flagged — the messages with the flagged flag 🚩
• msglist_deleted — the messages marked as deleted 🗑️
• msglist_marked — the messages with the marked flag ✅
• msglist_result — the messages which match the current search 🔍
• msglist_answered — the messages marked as answered ✉️
• msglist_forwarded — the messages marked as forwarded ➡️
• msglist_gutter — the message list gutter (the lil side strip, iykyk) 📏
• msglist_pill — the message list scrollbar 💊
• msglist_thread_folded — visible messages that have folded thread children 🧵
• msglist_thread_context — the messages not matching the mailbox / query, displayed for context 👀
• msglist_thread_orphan — threaded messages that have a missing parent message 😢
• dirlist_default — the default style for directories in the directory list 📁
• dirlist_unread — the style used for directories with unread messages 🍓
• dirlist_recent — the style used for directories with recent messages 🦋
• part_switcher — background for the part switcher in the message viewer 🧚
• part_filename — attachment file name in the part switcher 📎
• part_mimetype — attachment/part MIME type in the part switcher 🏷️

like, literally one per vibe, no notes 💜

okay so the style-object roster keeps going and honestly? iconic lineup 💅

• completion_default — The default style for the completion engine.
• completion_description — Completion item descriptions.
• completion_gutter — The completion gutter.
• completion_pill — The completion pill.
• tab — The style for the tab bar.
• stack — The style for ui stack element.
• spinner — The style for the loading spinner.
• border — The 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_default — The default style for the selector ui element.
• selector_focused — The focused item in a selector ui element.
• selector_chooser — The item chooser in a selector ui element.
• keyhint_default — The default style for the keyhint popup background.
• keyhint_key — The style for the key column in the keyhint popup.
• keyhint_desc — The style for the description column in the keyhint popup.

These next style objects only affect the built-in colorize filter and must be declared under a [viewer] section of the styleset file. no cap, that [viewer] part is lowkey important 🫶

• url — URLs.
• header — RFC-822-like header names.
• signature — Email signatures.
• diff_meta — Patch diff meta lines.
• diff_chunk — Patch diff chunks.
• diff_chunk_func — Patch diff chunk function names.
• diff_add — Patch diff added lines.
• diff_del — Patch diff deleted lines.
• diff_whitespace — Patch diff trailing whitespace.
• quote_1 — First level quoted text.
• quote_2 — Second level quoted text.
• quote_3 — Third level quoted text.
• quote_4 — Fourth level quoted text.
• quote_x — Above fourth level quoted text.
• code — Code blocks fenced by ``` and inline code.

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").

Example:

[user]
red.fg=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. it’s giving “teamwork makes the dream work” tbh ✨

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. bestie, this is your shortcut era 🎀

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 = blue — Set the foreground color of all style objects to blue.
• *list.bg = hotpink — Set 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. order matters, always has, always will 💅

💅 SELECTED MODIFIER

okay so the selected modifier is that girl who can show up to literally any party — it can be applied to any style object, no cap. The style you hand it gets layered on top of the style object it corresponds to. like a little accessory on the fit ✨

say you want messages flagged as read in the msglist to pop with a yellow foreground and black background? you literally just write:

msglist_default.selected.fg = yellow

msglist_default.selected.bg = black

and if we set the global style selected modifier using fnmatch, like this:

*.selected.reverse = toggle

then that toggles the reverse switch for the selected version of all the style objects at once. one line, every style, iconic behavior fr 🫶

here's the tea on inheritance tho: selected objects inherit from all the attributes of their non-selected counterparts. selected statements are parsed after the non-selected ones, and they effectively override the attributes of the non-selected style object. so yeah, they get the last word 💅

---

🧚 LAYERED STYLES

some styles — currently the msglist_* and dirlist_* ones — get applied in layers. if a style differs from the base (in this case *list_default) then that style applies, unless something higher up the stack overrides it. and if fg and bg colors aren't defined explicitly (or they're defined to the default color), they're considered "transparent" and the colors from the lower layer get used instead. it's giving sheer fabric over a solid base, lowkey genius 🌸

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_forwarded
6. msglist_flagged
7. msglist_deleted
8. msglist_result
9. msglist_thread_folded
10. msglist_thread_context
11. msglist_thread_orphan
12. msglist_marked

so yeah — the marked style will override all other msglist styles. main character energy, honestly 👑

the order for dirlist_* styles is:

1. dirlist_default
2. dirlist_unread
3. dirlist_recent

---

✨ DYNAMIC MESSAGE LIST STYLES

this is where it gets good. all msglist_* styles can be defined for specific email header values. the syntax is:

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

if <header_value> starts with a tilde character ~, it gets interpreted as a regular expression. and bestie, listen — if you're writing regular expressions that try to match with . or \. you need to wrap like this: ~/<expression>/. don't ask, just do it 💀

<header>,<header_value> can be specified multiple times to narrow down matches to more than one email header value. in that case, all the given headers must match for the dynamic style to apply. every single one. no partial credit 🎀

examples:

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
"msglist_*.From,~^Bob.Subject,~^(\[[w-]+]\s*)?\[(RFC )?PATCH.selected.fg" = #ffffaf
"msglist_*.List-ID,~/lists\.sr\.ht/selected.fg" = blue

when a dynamic style gets matched to an email header, it's used in priority compared to its non-dynamic counterpart. so like, provided this styleset:

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

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

and when multiple <header>,<header_value> pairs are given, the last style which matches all given patterns will be applied. provided this styleset:

msglist_*.From,~^Bob.Subject,~foobar.fg = red
msglist_*.From,~^Bob.fg = blue

an email from Bob with foobar in its subject will be colored in blue, since the second style is a full match too. order matters, bestie, always has 🦋

---

🌈 COLORS

the color values are set using any of the following methods:

• default — 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.

pick your fighter, they all slay 💖

---

🎀 DEFAULTS

before parsing a styleset, it first gets initialized with the following defaults:

*.selected.bg = 12
*.selected.fg = 15
*.selected.bold = true
statusline_*.dim = true
*warning.dim = false
*warning.bold = true
*warning.fg = 11
*success.dim = false
*success.bold = true
*success.fg = 10
*error.dim = false
*error.bold = true
*error.fg = 9
border.bg = 12
border.fg = 15
title.bg = 12
title.fg = 15
title.bold = true
header.fg = 4
header.bold = true
msglist_unread.bold = true
msglist_deleted.dim = true
msglist_marked.bg = 6
msglist_marked.fg = 15
msglist_pill.bg = 12
msglist_pill.fg = 15
part_mimetype.fg = 12
selector_chooser.bold = true
selector_focused.bold = true
selector_focused.bg = 12
selector_focused.fg = 15
completion_*.bg = 8
completion_pill.bg = 12
completion_default.fg = 15
completion_description.fg = 15
completion_description.dim = true

[viewer]
url.underline = true
url.fg = 3
header.bold = true
header.fg = 4
signature.dim = true
signature.fg = 4
diff_meta.bold = true
diff_chunk.fg = 6
diff_chunk_func.fg = 6
diff_chunk_func.dim = true
diff_add.fg = 2
diff_del.fg = 1
diff_whitespace.bg = 1
quote_1.fg = 6
quote_2.fg = 4
quote_3.fg = 6
quote_3.dim = true
quote_4.fg = 4
quote_4.dim = true
quote_x.fg = 5
quote_x.dim = true
code = 5

you can choose either to reset everything (except in the [viewer] section) by starting your styleset with these two lines:

*.default=true
*.normal=true

or selectively override style object attributes. both are valid, do what feels right 🌸

and if you want to also reset the [viewer] section, you need to insert the same two lines:

[viewer]
*.default=true
*.normal=true

okay that's genuinely everything — go forth and make your aerc look absolutely stunning, no notes 💜

---

💖 SEE ALSO

aerc(1) aerc-config(5)

---

👑 AUTHORS

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/.

---

and that's a wrap on AERC-STYLESETS(7), dated 2026-09-07 — you read the whole thing bestie, I'm so proud of you 😭🫶 go style something iconic ✨💅