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.

Using the linter

Use the supplied linting tool to check for errors and missing scopes:

cargo xtask themelint onedark # replace onedark with <name>
+

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 underlined modifier is deprecated and only available for backwards compatibility. +Its behavior is equivalent to setting underline.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"
+

Rainbow

The rainbow key is used for rainbow highlight for matching brackets. +The key is a list of styles.

rainbow = ["#ff0000", "#ffa500", "#fff000", { fg = "#00ff00", modifiers = ["bold"] }]
+

Colors from the palette and modifiers may be used.

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 - Types
+
- builtin - Primitive types provided by the language (int, usize)
- enum +
  - variant
  +
+
+
constructor
+
+
constant (TODO: constant.other.placeholder for %v)
+
- builtin Special constants provided by the language (true, false, nil etc) +
  - boolean
  +
- character +
  - escape
  +
- numeric (numbers) +
  - integer
  - float
  +
+
+
string (TODO: string.quoted.{single, double}, string.raw/.unquoted)?
+
- regexp - Regular expressions
- special +
  - path
  - url
  - symbol - Erlang/Elixir atoms, Ruby symbols, Clojure keywords
  +
+
+
comment - Code comments
+
- line - Single line comments (//)
- block - Block comments (e.g. (/* */) +
  - documentation - Documentation comments (e.g. /// in Rust)
  +
+
+
variable - Variables
+
- builtin - Reserved language variables (self, this, super, etc.)
- parameter - Function parameters
- other +
  - member - Fields of composite data types (e.g. structs, unions)
  +
+
+
label
+
+
punctuation
+
- delimiter - Commas, colons
- bracket - Parentheses, angle brackets, etc.
- special - String interpolation brackets.
+
+
keyword
+
- control +
  - conditional - if, else
  - repeat - for, while, loop
  - import - import, export
  - return
  - exception
  +
- operator - or, in
- directive - Preprocessor directives (#if in C)
- function - fn, func
- storage - Keywords describing how things are stored +
  - type - The type of something, class, function, var, let, etc.
  - modifier - Storage modifiers like static, mut, const, ref, etc.
  +
+
+
operator - ||, +=, >
+
+
function
+
- builtin
- method
- macro
- special (preprocessor in C)
+
+
tag - Tags (e.g. <body> in HTML)
+
- builtin
+
+
namespace
+
+
special
+
+
markup
+
- heading +
  - marker
  - 1, 2, 3, 4, 5, 6 - heading text for h1 through h6
  +
- list +
  - unnumbered
  - numbered
  - checked
  - unchecked
  +
- bold
- italic
- strikethrough
- link +
  - url - URLs pointed to by links
  - label - non-URL link references
  - text - URL and image descriptions in links
  +
- quote
- raw +
  - inline
  - block
  +
+
+
diff - version control changes
+
- plus - additions +
  - gutter - gutter indicator
  +
- minus - deletions +
  - gutter - gutter indicator
  +
- delta - modifications +
  - moved - renamed or moved files/changes
  - gutter - gutter indicator
  +
+

Interface

These scopes are used for theming the editor interface:

markup +
- normal +
  - completion - for completion doc popup UI
  - hover - for hover popup UI
  +
- heading +
  - completion - for completion doc popup UI
  - hover - for hover popup UI
  +
- raw +
  - inline +
    - completion - for completion doc popup UI
    - hover - 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.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`	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.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)