plugins.vim-matchup.settings

The configuration options for vim-matchup without the matchup_ prefix.

For example, the following settings are equivialent to these :setglobal commands:

  • foo_bar = 1 -> :setglobal matchup_foo_bar=1
  • hello = "world" -> :setglobal matchup_hello="world"
  • some_toggle = true -> :setglobal matchup_some_toggle
  • other_toggle = false -> :setglobal nomatchup_other_toggle

Type: attribute set of anything

Default: { }

Example:

{
  matchparen_offscreen = {
    method = "popup";
  };
  mouse_enabled = 0;
  surround_enabled = 1;
  transmute_enabled = 1;
}

Declared by:

plugins.vim-matchup.settings.enabled

Set to 0 to disable the plugin entirely.

Type: null or (one of 0, 1) or raw lua code

Default: null

Plugin default: 1

Declared by:

plugins.vim-matchup.settings.delim_count_fail

When disabled (default), giving an invalid count to the |[%| and |]%| motions and the text objects |i%| and |a%| will cause the motion or operation to fail.

When enabled, they will move as far as possible.

Note: targeting high counts when this option is enabled can become slow because many positions need to be tried before giving up.

Type: null or (one of 0, 1) or raw lua code

Default: null

Plugin default: 0

Declared by:

plugins.vim-matchup.settings.delim_nomids

If set to 1, middle words (like return) are not matched to start and end words for highlighting and motions.

Type: null or (one of 0, 1) or raw lua code

Default: null

Plugin default: 0

Declared by:

plugins.vim-matchup.settings.delim_noskips

This option controls whether matching is done within strings and comments.

  • By default, it is set to 0 which means all valid matches are made within strings and comments.
  • If set to 1, symbols like () will still be matched but words like for and end will not.
  • If set to 2, nothing will be matched within strings and comments.

Type: null or one of 0, 1, 2 or raw lua code

Default: null

Plugin default: 0

Declared by:

plugins.vim-matchup.settings.delim_start_plaintext

When enabled (the default), the plugin will be loaded for all buffers, including ones without a file type set.

This allows matching to be done in new buffers and plain text files but adds a small start-up cost to vim.

Type: null or (one of 0, 1) or raw lua code

Default: null

Plugin default: 1

Declared by:

plugins.vim-matchup.settings.delim_stopline

Configures the number of lines to search in either direction while using motions and text objects. Does not apply to match highlighting (see matchparen_stopline instead).

Type: null or unsigned integer, meaning >=0, or raw lua code

Default: null

Plugin default: 1500

Declared by:

plugins.vim-matchup.settings.mappings_enabled

Set to 0 to disable all mappings.

Type: null or (one of 0, 1) or raw lua code

Default: null

Plugin default: 1

Declared by:

plugins.vim-matchup.settings.matchparen_deferred

Deferred highlighting improves cursor movement performance (for example, when using |hjkl|) by delaying highlighting for a short time and waiting to see if the cursor continues moving.

Type: null or (one of 0, 1) or raw lua code

Default: null

Plugin default: 0

Declared by:

plugins.vim-matchup.settings.matchparen_deferred_fade_time

When set to {time} in milliseconds, the deferred highlighting behavior is changed in two ways:

  1. Highlighting of matches is preserved for at least {time} even when the cursor is moved away.
  2. If the cursor stays on the same match for longer than {time}, highlighting is cleared.

The effect is that highlighting occurs momentarily and then disappears, regardless of where the cursor is. It is possible that fading takes longer than {time}, if vim is busy doing other things.

This value should be greater than the deferred show delay.

Type: null or unsigned integer, meaning >=0, or raw lua code

Default: null

Plugin default: 0

Declared by:

plugins.vim-matchup.settings.matchparen_deferred_hide_delay

If the cursor has not stopped moving, assume highlight is stale after this many milliseconds.

Stale highlights are hidden.

Type: null or unsigned integer, meaning >=0, or raw lua code

Default: null

Plugin default: 700

Declared by:

plugins.vim-matchup.settings.matchparen_deferred_show_delay

Delay, in milliseconds, between when the cursor moves and when we start checking if the cursor is on a match.

Applies to both making highlights and clearing them for deferred highlighting.

Type: null or unsigned integer, meaning >=0, or raw lua code

Default: null

Plugin default: 50

Declared by:

plugins.vim-matchup.settings.matchparen_enabled

This option can disable match highlighting at |startup|.

Note: vim’s built-in plugin |pi_paren| plugin is also disabled. The variable g:loaded_matchparen has no effect on match-up.

You can also enable and disable highlighting for specific buffers using the variable |b:matchup_matchparen_enabled|.

Type: null or (one of 0, 1) or raw lua code

Default: null

Plugin default: 1

Declared by:

plugins.vim-matchup.settings.matchparen_end_sign

Configure the virtual symbol shown for closeless matches in languages like C++ and python.

if (true)
  cout << "";
else
  cout << ""; ◀ if

Type: null or string or raw lua code

Default: null

Plugin default: "◀"

Declared by:

plugins.vim-matchup.settings.matchparen_hi_background

Highlight buffer background between matches. This uses the MatchBackground highlighting group and is linked to ColorColumn by default.

Type: null or (one of 0, 1) or raw lua code

Default: null

Plugin default: 0

Declared by:

plugins.vim-matchup.settings.matchparen_hi_surround_always

Always highlight the surrounding words, if possible. This is like |<plug>(matchup-hi-surround)| but is updated each time the cursor moves.

This requires deferred matching (matchparen_deferred = 1).

Type: null or (one of 0, 1) or raw lua code

Default: null

Plugin default: 0

Declared by:

plugins.vim-matchup.settings.matchparen_insert_timeout

Adjust the timeouts in milliseconds for highlighting.

Type: null or unsigned integer, meaning >=0, or raw lua code

Default: null

Plugin default: 60

Declared by:

plugins.vim-matchup.settings.matchparen_nomode

When not empty, match highlighting will be disabled in the specified modes, where each mode is a single character like in the |mode()| function.

E.g., to disable highlighting in insert mode,

matchparen_nomode = "i";

and in visual modes,

matchparen_nomode = "vV\<c-v>";

Note: In visual modes, this takes effect only after moving the cursor.

Type: null or string or raw lua code

Default: null

Plugin default: ""

Example: "vV<c-v>"

Declared by:

plugins.vim-matchup.settings.matchparen_pumvisible

If set to 1, matches will be made even when the |popupmenu-completion| is visible.

If you use an auto-complete plugin which interacts badly with matching, set this option to 0.

Type: null or (one of 0, 1) or raw lua code

Default: null

Plugin default: 1

Declared by:

plugins.vim-matchup.settings.matchparen_singleton

Whether or not to highlight recognized words even if there is no match.

Type: null or (one of 0, 1) or raw lua code

Default: null

Plugin default: 0

Declared by:

plugins.vim-matchup.settings.matchparen_stopline

The number of lines to search in either direction while highlighting matches.

Set this conservatively since high values may cause performance issues.

Type: null or unsigned integer, meaning >=0, or raw lua code

Default: null

Plugin default: 400

Declared by:

plugins.vim-matchup.settings.matchparen_timeout

Adjust the timeouts in milliseconds for highlighting.

Type: null or unsigned integer, meaning >=0, or raw lua code

Default: null

Plugin default: 300

Declared by:

plugins.vim-matchup.settings.motion_cursor_end

If enabled, cursor will land on the end of mid and close words while moving downwards (|%|/|]%|). While moving upwards (|g%|, |[%|) the cursor will land on the beginning. Set to 0 to disable.

Note: this has no effect on operators: d% will delete |inclusive| of the ending word (this is compatible with matchit).

Type: null or (one of 0, 1) or raw lua code

Default: null

Plugin default: 1

Declared by:

plugins.vim-matchup.settings.motion_enabled

Set to 0 to disable motions (|matchup-%|, |%|, |[%|, |]%|).

Type: null or (one of 0, 1) or raw lua code

Default: null

Plugin default: 1

Declared by:

plugins.vim-matchup.settings.motion_override_Npercent

In vim, {count}% goes to the {count} percentage in the file (see |N%|). match-up overrides this motion for small {count} (by default, anything less than 7).

  • For example, to allow {count}% for {count} less than 12, set it to 11.
  • To disable this feature, and restore vim’s default {count}%, set it to 0.
  • To always enable this feature, use any value greater than 99.

Type: null or unsigned integer, meaning >=0, or raw lua code

Default: null

Plugin default: 6

Declared by:

plugins.vim-matchup.settings.mouse_enabled

Set to 0 to disable selecting matches with double click.

Type: null or (one of 0, 1) or raw lua code

Default: null

Plugin default: 1

Declared by:

plugins.vim-matchup.settings.override_vimtex

By default, match-up is disabled for tex files when the plugin |vimtex| is detected.

To enable match-up for tex files, set this option to 1. This will replace vimtex’s built-in highlighting and % map.

Note: matching may be computationally intensive for complex LaTeX documents. If you experience slowdowns, consider also setting matchparen_deferred to 1.

Type: null or (one of 0, 1) or raw lua code

Default: null

Plugin default: 0

Declared by:

plugins.vim-matchup.settings.surround_enabled

Enables the surround module which provides maps |ds%| and |cs%|.

Type: null or (one of 0, 1) or raw lua code

Default: null

Plugin default: 0

Declared by:

plugins.vim-matchup.settings.text_obj_enabled

Set to 0 to disable text objects (|a%|, |i%|).

Type: null or (one of 0, 1) or raw lua code

Default: null

Plugin default: 1

Declared by:

plugins.vim-matchup.settings.text_obj_linewise_operators

Modifies the set of operators which may operate line-wise with |i%| (see |matchup-feat-linewise|).

You may use "v", "V", and "\<c-v>" (i.e., an actual CTRL-V character) to specify the corresponding visual mode.

You can also specify custom plugin operators with ‘g@’ and optionally, an expression separated by a comma.

Type: null or (list of (string or raw lua code))

Default: null

Plugin default:

[
  "d"
  "y"
]

Declared by:

plugins.vim-matchup.settings.transmute_enabled

Set to 1 to enable the experimental transmute feature (|matchup-transmute|).

Type: null or (one of 0, 1) or raw lua code

Default: null

Plugin default: 0

Declared by: