13 KiB
Configuration
To override global configuration parameters, create a config.toml
file located in your config directory:
- Linux and Mac:
~/.config/helix/config.toml
- Windows:
%AppData%\helix\config.toml
💡 You can easily open the config file by typing
:config-open
within Helix normal mode.
Example config:
theme = "onedark"
[editor]
line-number = "relative"
mouse = false
[editor.cursor-shape]
insert = "bar"
normal = "block"
select = "underline"
[editor.file-picker]
hidden = false
You can use a custom configuration file by specifying it with the -c
or
--config
command line argument, for example hx -c path/to/custom-config.toml
.
Additionally, you can reload the configuration file by sending the USR1
signal to the Helix process on Unix operating systems, such as by using the command pkill -USR1 hx
.
Editor
[editor]
Section
Key | Description | Default |
---|---|---|
scrolloff |
Number of lines of padding around the edge of the screen when scrolling | 5 |
mouse |
Enable mouse mode | true |
middle-click-paste |
Middle click paste support | true |
scroll-lines |
Number of lines to scroll per scroll wheel step | 3 |
shell |
Shell to use when running external commands | Unix: ["sh", "-c"] Windows: ["cmd", "/C"] |
line-number |
Line number display: absolute simply shows each line's number, while relative shows the distance from the current line. When unfocused or in insert mode, relative will still show absolute line numbers |
absolute |
cursorline |
Highlight all lines with a cursor | false |
cursorcolumn |
Highlight all columns with a cursor | false |
gutters |
Gutters to display: Available are diagnostics and diff and line-numbers and spacer , note that diagnostics also includes other features like breakpoints, 1-width padding will be inserted if gutters is non-empty |
["diagnostics", "spacer", "line-numbers", "spacer", "diff"] |
auto-completion |
Enable automatic pop up of auto-completion | true |
auto-format |
Enable automatic formatting on save | true |
auto-save |
Enable automatic saving on the focus moving away from Helix. Requires focus event support from your terminal | false |
idle-timeout |
Time in milliseconds since last keypress before idle timers trigger. Used for autocompletion, set to 0 for instant | 400 |
completion-trigger-len |
The min-length of word under cursor to trigger autocompletion | 2 |
auto-info |
Whether to display info boxes | true |
true-color |
Set to true to override automatic detection of terminal truecolor support in the event of a false negative |
false |
rulers |
List of column positions at which to display the rulers. Can be overridden by language specific rulers in languages.toml file |
[] |
bufferline |
Renders a line at the top of the editor displaying open buffers. Can be always , never or multiple (only shown if more than one buffer is in use) |
never |
color-modes |
Whether to color the mode indicator with different colors depending on the mode itself | false |
text-width |
Maximum line length. Used for the :reflow command and soft-wrapping if soft-wrap.wrap_at_text_width is set |
80 |
[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:
Key | Description | Default |
---|---|---|
left |
A list of elements aligned to the left of the statusline | ["mode", "spinner", "file-name"] |
center |
A list of elements aligned to the middle of the statusline | [] |
right |
A list of elements aligned to the right of the statusline | ["diagnostics", "selections", "position", "file-encoding"] |
separator |
The character used to separate elements in the statusline | "│" |
mode.normal |
The text shown in the mode element for normal mode |
"NOR" |
mode.insert |
The text shown in the mode element for insert mode |
"INS" |
mode.select |
The text shown in the mode element for select mode |
"SEL" |
The following statusline elements can be configured:
Key | Description |
---|---|
mode |
The current editor mode (mode.normal /mode.insert /mode.select ) |
spinner |
A progress spinner indicating LSP activity |
file-name |
The path/name of the opened file |
file-base-name |
The basename of the opened file |
file-modification-indicator |
The indicator to show whether the file is modified (a [+] appears when there are unsaved changes) |
file-encoding |
The encoding of the opened file if it differs from UTF-8 |
file-line-ending |
The file line endings (CRLF or LF) |
total-line-numbers |
The total line numbers of the opened file |
file-type |
The type of the opened file |
diagnostics |
The number of warnings and/or errors |
workspace-diagnostics |
The number of warnings and/or errors on workspace |
selections |
The number of active selections |
primary-selection-length |
The number of characters currently in primary selection |
position |
The cursor position |
position-percentage |
The cursor position as a percentage of the total number of lines |
separator |
The string defined in editor.statusline.separator (defaults to "│" ) |
spacer |
Inserts a space between elements (multiple/contiguous spacers may be specified) |
[editor.lsp]
Section
Key | Description | Default |
---|---|---|
enable |
Enables LSP integration. Setting to false will completely disable language servers regardless of language settings. | true |
display-messages |
Display LSP progress messages below statusline1 | false |
auto-signature-help |
Enable automatic popup of signature help (parameter hints) | true |
display-signature-help-docs |
Display docs under signature help popup | true |
[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.
Key | Description | Default |
---|---|---|
normal |
Cursor shape in normal mode | block |
insert |
Cursor shape in insert mode | block |
select |
Cursor shape in select mode | block |
[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.
Key | Description | Default |
---|---|---|
hidden |
Enables ignoring hidden files | true |
follow-links |
Follow symlinks instead of ignoring them | true |
deduplicate-links |
Ignore symlinks that point at files already shown in the picker | true |
parents |
Enables reading ignore files from parent directories | true |
ignore |
Enables reading .ignore files |
true |
git-ignore |
Enables reading .gitignore files |
true |
git-global |
Enables reading global .gitignore , whose path is specified in git's config: core.excludefile option |
true |
git-exclude |
Enables reading .git/info/exclude files |
true |
max-depth |
Set with an integer value for maximum depth to recurse | Defaults to None . |
[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.search]
Section
Search specific options.
Key | Description | Default |
---|---|---|
smart-case |
Enable smart case regex searching (case-insensitive unless pattern contains upper case characters) | true |
wrap-around |
Whether the search should wrap after depleting the matches | true |
[editor.whitespace]
Section
Options for rendering whitespace with visible characters. Use :set whitespace.render all
to temporarily enable visible whitespace.
Key | Description | Default |
---|---|---|
render |
Whether to render whitespace. May either be "all" or "none" , or a table with sub-keys space , nbsp , tab , and newline |
"none" |
characters |
Literal characters to use when rendering whitespace. Sub-keys may be any of tab , space , nbsp , newline or tabpad |
See example below |
Example
[editor.whitespace]
render = "all"
# or control each character
[editor.whitespace.render]
space = "all"
tab = "all"
newline = "none"
[editor.whitespace.characters]
space = "·"
nbsp = "⍽"
tab = "→"
newline = "⏎"
tabpad = "·" # Tabs will look like "→···" (depending on tab width)
[editor.indent-guides]
Section
Options for rendering vertical indent guides.
Key | Description | Default |
---|---|---|
render |
Whether to render indent guides | false |
character |
Literal character to use for rendering the indent guide | │ |
skip-levels |
Number of indent levels to skip | 0 |
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.
Key | Description | Default |
---|---|---|
layout |
A vector of gutters to display | ["diagnostics", "spacer", "line-numbers", "spacer", "diff"] |
Example:
[editor.gutters]
layout = ["diff", "diagnostics", "line-numbers", "spacer"]
[editor.gutters.line-numbers]
Section
Options for the line number gutter
Key | Description | Default |
---|---|---|
min-width |
The minimum number of characters to use | 3 |
Example:
[editor.gutters.line-numbers]
min-width = 1
[editor.gutters.diagnotics]
Section
Currently unused
[editor.gutters.diff]
Section
Currently unused
[editor.gutters.spacer]
Section
Currently unused
[editor.soft-wrap]
Section
Options for soft wrapping lines that exceed the view width:
Key | Description | Default |
---|---|---|
enable |
Whether soft wrapping is enabled. | false |
max-wrap |
Maximum free space left at the end of the line. | 20 |
max-indent-retain |
Maximum indentation to carry over when soft wrapping a line. | 40 |
wrap-indicator |
Text inserted before soft wrapped lines, highlighted with ui.virtual.wrap |
↪ |
wrap-at-text-width |
Soft wrap at text-width instead of using the full viewport size. |
false |
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
-
By default, a progress spinner is shown in the statusline beside the file path. ↩︎