Themes
To use a theme add theme = "<name>" to the top of your config.toml file, or select it during runtime using :theme <name>.
Creating a theme
Create a file with the name of your theme as the file name (i.e mytheme.toml) and place it in your themes directory (i.e ~/.config/helix/themes or %AppData%\helix\themes on Windows). The directory might have to be created beforehand.
💡 The names "default" and "base16_default" are reserved for built-in themes and cannot be overridden by user-defined themes.
Overview
Each line in the theme file is specified as below:
key = { fg = "#ffffff", bg = "#000000", underline = { color = "#ff0000", style = "curl"}, modifiers = ["bold", "italic"] }
Where key represents what you want to style, fg specifies the foreground color, bg the background color, underline the underline style/color, and modifiers is a list of style modifiers. bg, underline and modifiers can be omitted to defer to the defaults.
To specify only the foreground color:
key = "#ffffff"
If the key contains a dot '.', it must be quoted to prevent it being parsed as a dotted key.
"key.key" = "#ffffff"
For inspiration, you can find the default theme.toml
here and
user-submitted themes
here.
The details of theme creation
Color palettes
It's recommended to define a palette of named colors, and refer to them in the
configuration values in your theme. To do this, add a table called
palette to your theme file:
"ui.background" = "white"
"ui.text" = "black"
[palette]
white = "#ffffff"
black = "#000000"
Keep in mind that the [palette] table includes all keys after its header,
so it should be defined after the normal theme options.
The default palette uses the terminal's default 16 colors, and the colors names
are listed below. The [palette] section in the config file takes precedence
over it and is merged into the default palette.
| Color Name |
|---|
default |
black |
red |
green |
yellow |
blue |
magenta |
cyan |
gray |
light-red |
light-green |
light-yellow |
light-blue |
light-magenta |
light-cyan |
light-gray |
white |
Modifiers
The following values may be used as modifier, provided they are supported by your terminal emulator.
| Modifier |
|---|
bold |
dim |
italic |
underlined |
slow_blink |
rapid_blink |
reversed |
hidden |
crossed_out |
💡 The
underlinedmodifier is deprecated and only available for backwards compatibility. Its behavior is equivalent to settingunderline.style="line".
Underline style
One of the following values may be used as a value for underline.style, providing it is
supported by your terminal emulator.
| Modifier |
|---|
line |
curl |
dashed |
dotted |
double_line |
Inheritance
Extend other themes by setting the inherits property to an existing theme.
inherits = "boo_berry"
# Override the theming for "keyword"s:
"keyword" = { fg = "gold" }
# Override colors in the palette:
[palette]
berry = "#2A2A4D"
Scopes
The following is a list of scopes available to use for styling:
Syntax highlighting
These keys match tree-sitter scopes.
When determining styling for a highlight, the longest matching theme key will be used. For example, if the highlight is function.builtin.static, the key function.builtin will be used instead of function.
We use a similar set of scopes as Sublime Text. See also TextMate scopes.
-
attribute- Class attributes, HTML tag attributes -
type- Typesbuiltin- Primitive types provided by the language (int,usize)parameter- Generic type parameters (T)enumvariant
-
constructor -
constant(TODO: constant.other.placeholder for%v)builtinSpecial constants provided by the language (true,false,niletc)boolean
characterescape
numeric(numbers)integerfloat
-
string(TODO: string.quoted.{single, double}, string.raw/.unquoted)?regexp- Regular expressionsspecialpathurlsymbol- Erlang/Elixir atoms, Ruby symbols, Clojure keywords
-
comment- Code commentsline- Single line comments (//)block- Block comments (e.g. (/* */)documentation- Documentation comments (e.g.///in Rust)
-
variable- Variablesbuiltin- Reserved language variables (self,this,super, etc.)parameter- Function parametersothermember- Fields of composite data types (e.g. structs, unions)private- Private fields that use a unique syntax (currently just ECMAScript-based languages)
-
label -
punctuationdelimiter- Commas, colonsbracket- Parentheses, angle brackets, etc.special- String interpolation brackets.
-
keywordcontrolconditional-if,elserepeat-for,while,loopimport-import,exportreturnexception
operator-or,indirective- Preprocessor directives (#ifin C)function-fn,funcstorage- Keywords describing how things are storedtype- The type of something,class,function,var,let, etc.modifier- Storage modifiers likestatic,mut,const,ref, etc.
-
operator-||,+=,> -
functionbuiltinmethodprivate- Private methods that use a unique syntax (currently just ECMAScript-based languages)
macrospecial(preprocessor in C)
-
tag- Tags (e.g.<body>in HTML)builtin
-
namespace -
special -
markupheadingmarker1,2,3,4,5,6- heading text for h1 through h6
listunnumberednumberedcheckedunchecked
bolditalicstrikethroughlinkurl- URLs pointed to by linkslabel- non-URL link referencestext- URL and image descriptions in links
quoterawinlineblock
-
diff- version control changesplus- additionsgutter- gutter indicator
minus- deletionsgutter- gutter indicator
delta- modificationsmoved- renamed or moved files/changesconflict- merge conflictsgutter- gutter indicator
Interface
These scopes are used for theming the editor interface:
markupnormalcompletion- for completion doc popup UIhover- for hover popup UI
headingcompletion- for completion doc popup UIhover- for hover popup UI
rawinlinecompletion- for completion doc popup UIhover- for hover popup UI
| Key | Notes |
|---|---|
ui.background | |
ui.background.separator | Picker separator below input line |
ui.cursor | |
ui.cursor.normal | |
ui.cursor.insert | |
ui.cursor.select | |
ui.cursor.match | Matching bracket etc. |
ui.cursor.primary | Cursor with primary selection |
ui.cursor.primary.normal | |
ui.cursor.primary.insert | |
ui.cursor.primary.select | |
ui.debug.breakpoint | Breakpoint indicator, found in the gutter |
ui.debug.active | Indicator for the line at which debugging execution is paused at, found in the gutter |
ui.gutter | Gutter |
ui.gutter.selected | Gutter for the line the cursor is on |
ui.highlight.frameline | Line at which debugging execution is paused at |
ui.linenr | Line numbers |
ui.linenr.selected | Line number for the line the cursor is on |
ui.statusline | Statusline |
ui.statusline.inactive | Statusline (unfocused document) |
ui.statusline.normal | Statusline mode during normal mode (only if editor.color-modes is enabled) |
ui.statusline.insert | Statusline mode during insert mode (only if editor.color-modes is enabled) |
ui.statusline.select | Statusline mode during select mode (only if editor.color-modes is enabled) |
ui.statusline.separator | Separator character in statusline |
ui.bufferline | Style for the buffer line |
ui.bufferline.active | Style for the active buffer in buffer line |
ui.bufferline.background | Style for bufferline background |
ui.popup | Documentation popups (e.g. Space + k) |
ui.popup.info | Prompt for multiple key options |
ui.window | Borderlines separating splits |
ui.help | Description box for commands |
ui.text | Default text style, command prompts, popup text, etc. |
ui.text.focus | The currently selected line in the picker |
ui.text.inactive | Same as ui.text but when the text is inactive (e.g. suggestions) |
ui.text.info | The key: command text in ui.popup.info boxes |
ui.virtual.ruler | Ruler columns (see the editor.rulers config) |
ui.virtual.whitespace | Visible whitespace characters |
ui.virtual.indent-guide | Vertical indent width guides |
ui.virtual.inlay-hint | Default style for inlay hints of all kinds |
ui.virtual.inlay-hint.parameter | Style for inlay hints of kind parameter (LSPs are not required to set a kind) |
ui.virtual.inlay-hint.type | Style for inlay hints of kind type (LSPs are not required to set a kind) |
ui.virtual.wrap | Soft-wrap indicator (see the editor.soft-wrap config) |
ui.virtual.jump-label | Style for virtual jump labels |
ui.menu | Code and command completion menus |
ui.menu.selected | Selected autocomplete item |
ui.menu.scroll | fg sets thumb color, bg sets track color of scrollbar |
ui.selection | For selections in the editing area |
ui.selection.primary | |
ui.highlight | Highlighted lines in the picker preview |
ui.cursorline.primary | The line of the primary cursor (if cursorline is enabled) |
ui.cursorline.secondary | The lines of any other cursors (if cursorline is enabled) |
ui.cursorcolumn.primary | The column of the primary cursor (if cursorcolumn is enabled) |
ui.cursorcolumn.secondary | The columns of any other cursors (if cursorcolumn is enabled) |
warning | Diagnostics warning (gutter) |
error | Diagnostics error (gutter) |
info | Diagnostics info (gutter) |
hint | Diagnostics hint (gutter) |
diagnostic | Diagnostics fallback style (editing area) |
diagnostic.hint | Diagnostics hint (editing area) |
diagnostic.info | Diagnostics info (editing area) |
diagnostic.warning | Diagnostics warning (editing area) |
diagnostic.error | Diagnostics error (editing area) |
diagnostic.unnecessary | Diagnostics with unnecessary tag (editing area) |
diagnostic.deprecated | Diagnostics with deprecated tag (editing area) |