Something went wrong. Try again.
Library of 45+ independent Lua modules improving Neovim experience with minimal effort nvim-mini.org/mini.nvim
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449*mini.keymap* Special key mappings
MIT License Copyright (c) 2025 Evgeni Chasnovski
------------------------------------------------------------------------------ *MiniKeymap*Features:
- Map keys to perform configurable multi-step actions: if condition for step one is true - execute step one action, else check step two, and so on until falling back to executing original keys. This is usually referred to as "smart" keys (like "smart tab"). See |MiniKeymap.map_multistep()|.
There are many built-in steps targeted for Insert mode mappings of special keys like <Tab>, <S-Tab>, <CR>, and <BS>: - Navigate and accept |popupmenu-completion|. Useful for |mini.completion|. - Navigate and expand |mini.snippets|. - Execute <CR> and <BS> respecting |mini.pairs|. - Jump before/after current tree-sitter node. - Jump before opening and after closing characters (brackets and quotes). - Increase/decrease indent when cursor is inside of it. - Delete all whitespace to the left ("hungry backspace"). - Navigate |vim.snippet|. - Navigate and accept in [hrsh7th/nvim-cmp](https://github.com/hrsh7th/nvim-cmp) completion. - Navigate and accept in [Saghen/blink.cmp](https://github.com/Saghen/blink.cmp) completion. - Navigate and expand [L3MON4D3/LuaSnip](https://github.com/L3MON4D3/LuaSnip) snippets. - Execute <CR> and <BS> respecting [windwp/nvim-autopairs](https://github.com/windwp/nvim-autopairs).
- Map keys as "combo": each key acts immediately plus execute extra action if all are typed within configurable delay between each other. See |MiniKeymap.map_combo()|. Some of the common use cases include: - Map insertable keys (like "jk", "kj") in Insert and Command-line mode to exit into Normal mode. - Fight against bad habits of pressing the same navigation key by showing a notification if there are too many of them pressed in a row.
Sources with more details:- |MiniKeymap-examples|
# Setup ~
This module doesn't need setup, but it can be done to improve usability.Setup with `require('mini.keymap').setup({})` (replace `{}` with your `config`table). It will create global Lua table `MiniKeymap` which you can use forscripting or manually (with `:lua MiniKeymap.*`).
See |MiniKeymap.config| for `config` structure and default values.
This module doesn't have runtime options, so using `vim.b.minikeymap_config`will have no effect here.
# Comparisons ~
- [max397574/better-escape.nvim](https://github.com/max397574/better-escape.nvim): - Mostly similar to |MiniKeymap.map_combo()| with a different approach to creating mappings. - Mostly targeted for Insert mode mappings as pressed keys get removed automatically after typed. This module allows more general cases while requiring explicit removal of keys (usually via explicit `<BS><BS>`).
- [abecodes/tabout.nvim](https://github.com/abecodes/tabout.nvim): - Similar general idea as in `'jump_{after,before}_tsnode'` steps of |MiniKeymap.map_multistep()|. - Works only with enabled tree-sitter parser. This module provides fallback via `'jump_after_close'` and `'jump_before_open'` that work without tree-sitter parser. - `tabout.nvim` has finer control of how the tree-sitter node movement is done, while this module has "jump outside of current node" behavior.
# Disabling ~
To disable acting in mappings, set `vim.g.minikeymap_disable` (globally) or`vim.b.minikeymap_disable` (for a buffer) to `true`. Considering high numberof different scenarios and customization intentions, writing exact rulesfor disabling module's functionality is left to user.See |mini.nvim-disabling-recipes| for common recipes.
------------------------------------------------------------------------------ *MiniKeymap-examples*# Multi-step ~
See |MiniKeymap.map_multistep()| for a general description of how multi-stepmappings work and what built-in steps are available.
Setup that works well with |mini.completion| and |mini.pairs|: >lua
local map_multistep = require('mini.keymap').map_multistep map_multistep('i', '<Tab>', { 'pmenu_next' }) map_multistep('i', '<S-Tab>', { 'pmenu_prev' }) map_multistep('i', '<CR>', { 'pmenu_accept', 'minipairs_cr' }) map_multistep('i', '<BS>', { 'minipairs_bs' })<Use <Tab> / <S-Tab> to also navigate and expand |mini.snippets|: >lua
local map_multistep = require('mini.keymap').map_multistep
local tab_steps = { 'minisnippets_next','minisnippets_expand','pmenu_next' } map_multistep('i', '<Tab>', tab_steps)
local shifttab_steps = { 'minisnippets_prev', 'pmenu_prev' } map_multistep('i', '<S-Tab>', shifttab_steps)<An extra smart <Tab> and <S-Tab>: >lua
local map_multistep = require('mini.keymap').map_multistep
-- NOTE: this will never insert tab, press <C-v><Tab> for that local tab_steps = { 'minisnippets_next', 'minisnippets_expand', 'pmenu_next', 'jump_after_tsnode', 'jump_after_close', } map_multistep('i', '<Tab>', tab_steps)
local shifttab_steps = { 'minisnippets_prev', 'pmenu_prev', 'jump_before_tsnode', 'jump_before_open', } map_multistep('i', '<S-Tab>', shifttab_steps)<Navigation in active |vim.snippet| session also requires mapping in |Select-mode|: >lua
local map_multistep = require('mini.keymap').map_multistep map_multistep({ 'i', 's' }, '<Tab>', { 'vimsnippet_next', 'pmenu_next' }) map_multistep({ 'i', 's' }, '<S-Tab>', { 'vimsnippet_prev', 'pmenu_prev' })<# Combos ~
See |MiniKeymap.map_combo()| for a general description of what is a combo andmore caveats about its usage.
All combos require their left hand side keys to be typed relatively quickly.To adjust the delay between keys, add `{ delay = 500 }` (use custom value) asfourth argument.
## "Better escape" to Normal mode ~
Leave into |Normal-mode| without having to reach for <Esc> key: >lua
-- Support most common modes. This can also contain 't', but would -- only mean to press `<Esc>` inside terminal. local mode = { 'i', 'c', 'x', 's' } require('mini.keymap').map_combo(mode, 'jk', '<BS><BS><Esc>')
-- To not have to worry about the order of keys, also map "kj" require('mini.keymap').map_combo(mode, 'kj', '<BS><BS><Esc>')
-- Escape into Normal mode from Terminal mode require('mini.keymap').map_combo('t', 'jk', '<BS><BS><C-\\><C-n>') require('mini.keymap').map_combo('t', 'kj', '<BS><BS><C-\\><C-n>')<## Show bad navigation habits ~
Show notification if there is too much movement by repeating same key: >lua
local notify_many_keys = function(key) local lhs = string.rep(key, 5) local action = function() vim.notify('Too many ' .. key) end require('mini.keymap').map_combo({ 'n', 'x' }, lhs, action) end notify_many_keys('h') notify_many_keys('j') notify_many_keys('k') notify_many_keys('l')<## Fix previous spelling mistake ~
Fix previous spelling mistake (see |[s| and |z=|) without manually leavingInsert mode: >lua
local action = '<BS><BS><Esc>[s1z=gi<Right>' require('mini.keymap').map_combo('i', 'kk', action)<## Hide search highlighting ~
Use double <Esc><Esc> to execute |:nohlsearch|. Although this can also be donewith `nmap <Esc> <Cmd>nohl<CR>`, the combo approach also exists and can be usedto free <Esc> mapping in Normal mode for something else. >lua
local action = function() vim.cmd('nohlsearch') end require('mini.keymap').map_combo({ 'n','i','x','c' }, '<Esc><Esc>', action)<## Buffer navigation ~
Replace some movements with easier to type alternatives: >lua
local map_combo = require('mini.keymap').map_combo map_combo({ 'n', 'x' }, 'll', 'g$') map_combo({ 'n', 'x' }, 'hh', 'g^') map_combo({ 'n', 'x' }, 'jj', '}') map_combo({ 'n', 'x' }, 'kk', '{')<------------------------------------------------------------------------------ *MiniKeymap.setup()* `MiniKeymap.setup`({config})Module setup
Parameters ~{config} `(table|nil)` Module config table. See |MiniKeymap.config|.
Usage ~>lua require('mini.keymap').setup({}) -- replace {} with your config table -- needs `keymap` field present<------------------------------------------------------------------------------ *MiniKeymap.config* `MiniKeymap.config`Defaults ~>lua MiniKeymap.config = {}<------------------------------------------------------------------------------ *MiniKeymap.map_multistep()* `MiniKeymap.map_multistep`({mode}, {lhs}, {steps}, {opts})Map multi-step action
Mapping of a multi-step action is an expression mapping (|:map-expression|).Executing a multi-step action is essentially:- Check condition for step one. If `true` - execute step one action and stop.- Check condition for step two, and so on.- If there is no more steps, fall back to returning mapped key.
For better user experience there are many built-in steps mostly designedto create Insert mode "smart" mappings of <Tab>, <S-Tab>, <CR>, and <BS>.Available built-in steps ("For key" is a suggestion, any can be used):> ┌─────────────────────┬────────────────┬──────────────────────────┬─────────┐ │ Step name │ Condition │ Action │ For key │ ├─────────────────────┴────────────────┴──────────────────────────┴─────────┤ ├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈ |ins-completion-menu| ┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤ │ pmenu_next │ Pmenu visible │ Select next (as <C-n>) │ <Tab> │ │ pmenu_prev │ Pmenu visible │ Select prev (as <C-p>) │ <S-Tab> │ │ pmenu_accept │ Item selected │ Accept (as <C-y>) │ <CR> │ ├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈ |mini.snippets| ┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤ │ minisnippets_next │ Session active │ Jump to next tabstop │ <Tab> │ │ minisnippets_prev │ Session active │ Jump to prev tabstop │ <S-Tab> │ │ minisnippets_expand │ Can expand │ Expand snippet at cursor │ <Tab> │ ├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈ |mini.pairs| ┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤ │ minipairs_cr │ Module set up │ <CR> respecting pairs │ <CR> │ │ minipairs_bs │ Module set up │ <BS> respecting pairs │ <BS> │ ├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈ Jump around in Insert mode ┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤ │ jump_after_tsnode │ TS parser │ Jump after node end │ <Tab> │ │ jump_before_tsnode │ TS parser │ Jump before node start │ <S-Tab> │ │ jump_after_close │ Insert mode │ Jump after )]}"'` │ <Tab> │ │ jump_before_open │ Insert mode │ Jump before ([{"'` │ <S-Tab> │ ├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈ Work with whitespace ┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤ │ increase_indent │ Is on indent │ Increase indent │ <Tab> │ │ decrease_indent │ Is on indent │ Decrease indent │ <S-Tab> │ │ hungry_bs │ Space to left │ Delete all space to left │ <BS> │ ├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈ |vim.snippet| ┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤ │ vimsnippet_next │ Session active │ Jump to next tabstop │ <Tab> │ │ vimsnippet_prev │ Session active │ Jump to prev tabstop │ <S-Tab> │ ├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈ 'hrsh7th/nvim-cmp' ┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤ │ cmp_next │ Menu visible │ Select next item │ <Tab> │ │ cmp_prev │ Menu visible │ Select prev item │ <S-Tab> │ │ cmp_accept │ Item selected │ Accept selected item │ <CR> │ ├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈ 'Saghen/blink.cmp' ┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤ │ blink_next │ Menu visible │ Select next item │ <Tab> │ │ blink_prev │ Menu visible │ Select prev item │ <S-Tab> │ │ blink_accept │ Item selected │ Accept selected item │ <CR> │ ├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈ 'L3MON4D3/LuaSnip' ┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤ │ luasnip_next │ Session active │ Jump to next tabstop │ <Tab> │ │ luasnip_prev │ Session active │ Jump to prev tabstop │ <S-Tab> │ │ luasnip_expand │ Can expand │ Expand snippet at cursor │ <Tab> │ ├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈ 'windwp/nvim-autopairs' ┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤ │ nvimautopairs_cr │ Module present │ <CR> respecting pairs │ <CR> │ │ nvimautopairs_bs │ Module present │ <BS> respecting pairs │ <BS> │ └─────────────────────┴────────────────┴──────────────────────────┴─────────┘<Notes:- Executing action has limitations of |:map-expression| (like not allowed text or buffer changes, etc.). To execute complex lua code, use |vim.schedule()| inside action, return the code as string in |:map-cmd| format, or return a function to be later executed. See usage examples.
- Some mapped keys (like <Tab>, <CR>) might require disabling smart presets in plugins (like `nvim-cmp`, `blink-cmp`, `nvim-autopairs`).
Parameters ~{mode} `(string|table)` Same as for |vim.keymap.set()|.{lhs} `(string)` Same as for |vim.keymap.set()|.{steps} `(table)` Array of steps. Each step can be a string with the name of built-in step or a table with two callable methods (will be called without arguments): - <condition> - return `true` if the action should be executed. - <action> - action to be executed if <condition> returns `true`. For more flexibility, it can also return a value which can be: - String - will be returned as expression output. Can be something like `"<Tab>"` (treat as <Tab> key) or `"<Cmd>lua vim.notify('Hello')<CR>"`. Should not escape keycodes (i.e. return "<Tab>" and not "\t"). To undo already done escape, use |keytrans()|. - Function - will be executed as if `"<Cmd>lua f()<CR>"`, but does not need to create a global function for that. - `false` - do not stop going through steps.{opts} `(table|nil)` Same as for |vim.keymap.set()|.
Usage ~See |MiniKeymap-examples| for practical examples.
Some illustrative examples: >lua
_G.log = {} local steps = {} steps[1] = { condition = function() table.insert(_G.log, 'C1'); return _G.cond1 end, -- Compute and return keys. Will be emulated as pressed. action = function() table.insert(_G.log, 'A1'); return 'hello' end, }
steps[2] = { condition = function() table.insert(_G.log, 'C2'); return _G.cond2 end, -- Perform action immediately, return `false` to keep asking other steps action = function() table.insert(_G.log, 'A2'); return false end, }
steps[3] = { condition = function() table.insert(_G.log, 'C3'); return _G.cond3 end, -- Perform action later (to overcom expression mapping limitations) action = function() table.insert(_G.log, 'A3_1') return function() table.insert(_G.log, 'A3_2') end end, }
-- Make Insert mode <Tab> mapping require('mini.keymap').map_multistep('i', '<Tab>', steps)
-- Pressing <Tab> inserts fallback `\t`; logs C1+C2+C3 _G.cond1, _G.cond2, _G.cond3 = false, false, false
-- Pressing <Tab> inserts `hello`; logs C1+A1 _G.cond1, _G.cond2, _G.cond3 = true, false, false
-- Pressing <Tab> inserts nothing; logs C1+C2+A2+C3+A3_1+A3_2 _G.cond1, _G.cond2, _G.cond3 = false, true, true<------------------------------------------------------------------------------ *MiniKeymap.gen_step* `MiniKeymap.gen_step`Generate step for multi-step mappings
This is a table with function elements. Call to actually get a step.
------------------------------------------------------------------------------ *MiniKeymap.gen_step.search_pattern()* `MiniKeymap.gen_step.search_pattern`({pattern}, {flags}, {opts})Search pattern step
Use |search()| to jump to pattern match. Possibly adjust final position tobe just to the right of the match (useful in Insert mode).
Parameters ~{pattern} `(string)` Same as for |search()|.{flags} `(string|nil)` Same as for |search()|.{opts} `(table|nil)` Options. Possible fields: - <side> `(string)` - one of `"before"` (default) or `"after"`. - <stopline> `(number|function)` - forwarded to |search()| (as number or as function's output after calling it before every search). - <timeout> `(number)` - forwarded to |search()|. - <skip> `(string|function)` - forwarded to |search()|.
Return ~`(table)` Step which searches pattern.
Usage ~Built-in |MiniKeymap.map_multistep()| steps "jump_after_close" and"jump_before_open" use this, but only in Insert mode.
Steps that jump before/after all consecutive brackets in several modes: >lua
local keymap = require('mini.keymap') local tab_step_insert = keymap.gen_step.search_pattern( -- Need to use 'c' flag and 'after' side for robust "chaining" [=[[)\]}]\+]=], 'ceW', { side = 'after' } ) keymap.map_multistep('i', '<Tab>', { tab_step_insert }) local tab_step = keymap.gen_step.search_pattern([=[[)\]}]\+]=], 'eW') keymap.map_multistep({ 'n', 'x' }, '<Tab>', { tab_step })
local stab_step = keymap.gen_step.search_pattern([=[[(\[{]\+]=], 'bW') keymap.map_multistep({ 'i', 'n', 'x' }, '<S-Tab>', { stab_step })<------------------------------------------------------------------------------ *MiniKeymap.map_combo()* `MiniKeymap.map_combo`({mode}, {lhs}, {action}, {opts})Map combo post action
Create a combo: sequence of keys where each acts immediately plus executean extra action if all are typed within configurable delay between each other.
Example for Insert mode "better escape" `jk` combo with `<BS><BS><Esc>` action:- Press `j`. It is visible immediately without any side effects.- Quickly (no more than default 200 ms after) press `k`. This triggers the action which is equivalent to typing <BS><BS> (delete already present `jk`) and <Esc> to exit into Normal mode.
Notes:- IMPORTANT! Combo is not a regular mapping but a separate key tracking with |vim.on_key()|. This is important as combos will not be visible and can not be managed as regular mappings. Instead each combo is associated with a dedicated |namespace| (named for human readability). However, it is not really expected to manage them on the fly after they are created.
- String action is executed with |nvim_input()|, i.e. emulated keys will respect custom mappings.
- Different combos are tracked and act independent of each other. For example, if there are combos for `jjk` and `jk` keys, fast typing `jjk` will execute both.
- Neovim>=0.11 is recommended due to |vim.on_key()| improvement to allow watching for keys as they are typed and not as if coming from mappings. For example, this matters when creating a `jk` combo for Visual mode while also having `xnoremap j gj` style of remaps. On Neovim<0.11 the fix is to use `gjgk` as combo's left hand side.
- Each combo adds very small but non-zero overhead on each keystroke. Usually about 1-3 microseconds (i.e. 0.001-0.003 ms), which should be fast enough for most setups. For a "normal, real world" coding session with a total of ~20000 keystrokes it results in extra ~40ms of overhead for a single created combo. Create many combos with caution.
Parameters ~{mode} `(string|table)` String or array of string mode id (like "n", "i", etc.). Array of several modes is more performant than several single mode combos.{lhs} `(string|table)` String with tracked key sequence or an array of tracked keys (one element - one key).{action} `(string|function)` Action to perform after key sequence is detected. If string, treated as keys and emulated with |nvim_input()|. If function, executed in |vim.schedule()|. Can return string keys which will be emulated.{opts} `(table|nil)` Options. Possible fields: - <delay> `(number)` - delay in milliseconds within which keys should be pressed to detect a key sequence. Default: 200.
Usage ~See |MiniKeymap-examples| for practical examples.
Some illustrative examples: >lua
local map_combo = require('mini.keymap').map_combo
-- In Insert mode pressing `x` followed by `x` within 1 second logs 'A' -- and emulates extra pressing of `yy` _G.log = {} local action = function() table.insert(_G.log, 'A'); return 'yy' end map_combo('i', 'xx', action, { delay = 1000 })<
vim:tw=78:ts=8:noet:ft=help:norl: