Editor

• [editor] Section
• [editor.statusline] Section
• [editor.lsp] Section
• [editor.cursor-shape] Section
• [editor.file-picker] Section
• [editor.auto-pairs] Section
• [editor.search] Section
• [editor.whitespace] Section
• [editor.indent-guides] Section
• [editor.gutters] Section
  • [editor.gutters.line-numbers] Section
  • [editor.gutters.diagnostics] Section
  • [editor.gutters.diff] Section
  • [editor.gutters.spacer] Section
• [editor.soft-wrap] Section
• [editor.smart-tab] Section
• [editor.inline-diagnostics] Section

[editor] Section

[editor.clipboard-provider] Section

Helix can be configured either to use a builtin clipboard configuration or to use a provided command.

For instance, setting it to use OSC 52 termcodes, the configuration would be:

[editor]
clipboard-provider = "termcode"

Alternatively, Helix can be configured to use arbitary commands for clipboard integration:

[editor.clipboard-provider.custom]
yank = { command = "cat",  args = ["test.txt"] }
paste = { command = "tee",  args = ["test.txt"] }
primary-yank = { command = "cat",  args = ["test-primary.txt"] } # optional
primary-paste = { command = "tee",  args = ["test-primary.txt"] } # optional

For custom commands the contents of the yank/paste is communicated over stdin/stdout.

[editor.statusline] Section

Allows configuring the statusline at the bottom of the editor.

The configuration distinguishes between three areas of the status line:

[ ... ... LEFT ... ... | ... ... ... CENTER ... ... ... | ... ... RIGHT ... ... ]

Statusline elements can be defined as follows:

[editor.statusline]
left = ["mode", "spinner"]
center = ["file-name"]
right = ["diagnostics", "selections", "position", "file-encoding", "file-line-ending", "file-type"]
separator = "│"
mode.normal = "NORMAL"
mode.insert = "INSERT"
mode.select = "SELECT"

The [editor.statusline] key takes the following sub-keys:

The following statusline elements can be configured:

[editor.lsp] Section

[editor.cursor-shape] Section

Defines the shape of cursor in each mode. Valid values for these options are block, bar, underline, or hidden.

💡 Due to limitations of the terminal environment, only the primary cursor can change shape.

[editor.file-picker] Section

Set options for file picker and global search. Ignoring a file means it is not visible in the Helix file picker and global search.

All git related options are only enabled in a git repository.

Ignore files can be placed locally as .ignore or put in your home directory as ~/.ignore. They support the usual ignore and negative ignore (unignore) rules used in .gitignore files.

Additionally, you can use Helix-specific ignore files by creating a local .helix/ignore file in the current workspace or a global ignore file located in your Helix config directory:

• Linux and Mac: ~/.config/helix/ignore
• Windows: %AppData%\helix\ignore

Example:

# unignore in file picker and global search
!.github/
!.gitignore
!.gitattributes

[editor.auto-pairs] Section

Enables automatic insertion of pairs to parentheses, brackets, etc. Can be a simple boolean value, or a specific mapping of pairs of single characters.

To disable auto-pairs altogether, set auto-pairs to false:

[editor]
auto-pairs = false # defaults to `true`

The default pairs are (){}[]''""``, but these can be customized by setting auto-pairs to a TOML table:

[editor.auto-pairs]
'(' = ')'
'{' = '}'
'[' = ']'
'"' = '"'
'`' = '`'
'<' = '>'

Additionally, this setting can be used in a language config. Unless the editor setting is false, this will override the editor config in documents with this language.

Example languages.toml that adds <> and removes ''

[[language]]
name = "rust"

[language.auto-pairs]
'(' = ')'
'{' = '}'
'[' = ']'
'"' = '"'
'`' = '`'
'<' = '>'

[editor.auto-save] Section

Control auto save behavior.

[editor.search] Section

Search specific options.

[editor.whitespace] Section

Options for rendering whitespace with visible characters. Use :set whitespace.render all to temporarily enable visible whitespace.

Example

[editor.whitespace]
render = "all"
# or control each character
[editor.whitespace.render]
space = "all"
tab = "all"
nbsp = "none"
nnbsp = "none"
newline = "none"

[editor.whitespace.characters]
space = "·"
nbsp = "⍽"
nnbsp = "␣"
tab = "→"
newline = "⏎"
tabpad = "·" # Tabs will look like "→···" (depending on tab width)

[editor.indent-guides] Section

Options for rendering vertical indent guides.

Example:

[editor.indent-guides]
render = true
character = "╎" # Some characters that work well: "▏", "┆", "┊", "⸽"
skip-levels = 1

[editor.gutters] Section

For simplicity, editor.gutters accepts an array of gutter types, which will use default settings for all gutter components.

[editor]
gutters = ["diff", "diagnostics", "line-numbers", "spacer"]

To customize the behavior of gutters, the [editor.gutters] section must be used. This section contains top level settings, as well as settings for specific gutter components as subsections.

Example:

[editor.gutters]
layout = ["diff", "diagnostics", "line-numbers", "spacer"]

[editor.gutters.line-numbers] Section

Options for the line number gutter

Example:

[editor.gutters.line-numbers]
min-width = 1

[editor.gutters.diagnostics] Section

Currently unused

[editor.gutters.diff] Section

The diff gutter option displays colored bars indicating whether a git diff represents that a line was added, removed or changed. These colors are controlled by the theme attributes diff.plus, diff.minus and diff.delta.

Other diff providers will eventually be supported by a future plugin system.

There are currently no options for this section.

[editor.gutters.spacer] Section

Currently unused

[editor.soft-wrap] Section

Options for soft wrapping lines that exceed the view width:

Example:

[editor.soft-wrap]
enable = true
max-wrap = 25 # increase value to reduce forced mid-word wrapping
max-indent-retain = 0
wrap-indicator = ""  # set wrap-indicator to "" to hide it

[editor.smart-tab] Section

Options for navigating and editing using tab key.

Due to lack of support for S-tab in some terminals, the default keybindings don't fully embrace smart-tab editing experience. If you enjoy smart-tab navigation and a terminal that supports the Enhanced Keyboard protocol, consider setting extra keybindings:

[keys.normal]
tab = "move_parent_node_end"
S-tab = "move_parent_node_start"

[keys.insert]
S-tab = "move_parent_node_start"

[keys.select]
tab = "extend_parent_node_end"
S-tab = "extend_parent_node_start"

[editor.inline-diagnostics] Section

Options for rendering diagnostics inside the text like shown below

fn main() {
  let foo = bar;
            └─ no such value in this scope
}

The allowed values for cursor-line and other-lines are: error, warning, info, hint.

The (first) diagnostic with the highest severity that is not shown inline is rendered at the end of the line (as long as its severity is higher than the end-of-line-diagnostics config option):

fn main() {
  let baz = 1;
  let foo = bar; a local variable with a similar name exists: baz
            └─ no such value in this scope
}

The new diagnostic rendering is not yet enabled by default. As soon as end of line or inline diagnostics are enabled the old diagnostics rendering is automatically disabled. The recommended default setting are:

[editor]
end-of-line-diagnostics = "hint"
[editor.inline-diagnostics]
cursor-line = "warning" # show warnings and errors on the cursorline inline