gui-keymap.nvim

Use familiar GUI shortcuts in Neovim while learning native Vim commands.

Documentation

What this plugin does

gui-keymap.nvim adds a compatibility layer for users moving from GUI editors such as VSCode, Sublime Text, or JetBrains IDEs.

It provides:

copy, paste, cut, select all, undo, redo
save and save-and-close shortcuts
Home/End line movement
Shift+Arrow selection
word deletion with Ctrl+Backspace and Ctrl+Delete
optional Vim learning hints
conflict detection and diagnostics

Start here

Install the plugin.
Run :GuiKeymapDemo.
Test the shortcuts in the scratch buffer.
Open :GuiKeymapInfo if something does not behave as expected.

Project links

Repository: Only-Moon/gui-keymap.nvim
README: GitHub README

Installation

Requirements

Neovim >= 0.8.0
Classic Vim is not supported

lazy.nvim

{
  "Only-Moon/gui-keymap.nvim",
  opts = {},
}

packer.nvim

use({
  "Only-Moon/gui-keymap.nvim",
  config = function()
    require("gui-keymap").setup({})
  end,
})

vim-plug

Plug 'Only-Moon/gui-keymap.nvim'

Then:

require("gui-keymap").setup({})

Native packages

git clone https://github.com/Only-Moon/gui-keymap.nvim \
  ~/.local/share/nvim/site/pack/gui/start/gui-keymap.nvim

Then:

require("gui-keymap").setup({})

LuaRocks

luarocks install gui-keymap.nvim

Then:

require("gui-keymap").setup({})

First-run flow

If welcome notifications are enabled, the plugin shows a one-time onboarding message after a fresh install or after the plugin version changes.

Verify installation

Inside Neovim:

:GuiKeymapDemo
:GuiKeymapInfo
:checkhealth gui-keymap

Configuration Reference

Default configuration

require("gui-keymap").setup({
  undo_redo = true,
  clipboard = {
    copy = true,
    paste = true,
    cut = true,
  },
  select_all = true,
  delete_selection = true,
  shift_selection = true,
  word_delete = true,
  save = true,
  quit = true,
  home_end = true,
  yanky_integration = true,
  hint_enabled = true,
  hint_repeat = 3,
  hint_persist = true,
  which_key_integration = true,
  enforce_on_startup = true,
  force_priority = true,
  show_welcome = true,
  preserve_mode = true,
})

If you pass no options, these defaults are used automatically.

Option reference

`undo_redo`

Enables Ctrl+Z and Ctrl+Y mappings in normal and insert mode.

`clipboard.copy`

Enables GUI-style copy mappings:

visual Ctrl+C
normal Ctrl+C

`clipboard.paste`

Enables GUI-style paste mappings:

normal Ctrl+V
insert Ctrl+V

`clipboard.cut`

Enables GUI-style cut mapping in visual mode with Ctrl+X.

`select_all`

Enables Ctrl+A select-all behavior.

`delete_selection`

Enables visual-mode deletion using:

Backspace
Delete

These use the black-hole register to avoid overwriting clipboard content.

`shift_selection`

Enables GUI-style selection growth using Shift+Arrow keys in normal, visual, and insert mode.

This feature is terminal-sensitive. Some terminals emit fallback keycodes such as <kL> or <kR> instead of literal Shift+Arrow sequences.

`word_delete`

Enables:

Ctrl+Backspace
Ctrl+Delete

Mapped to GUI-style word deletion behavior that avoids polluting clipboard state.

`save`

Enables Ctrl+S to save the current buffer.

Modes:

normal
insert
visual

`quit`

Enables Ctrl+Q to save and close the current file.

Behavior:

saves pending changes
runs :confirm wq

`home_end`

Enables Home and End mappings in normal, insert, and visual mode.

Behavior:

Home -> line start
End -> line end

`yanky_integration`

If yanky.nvim is installed, clipboard actions prefer Yanky-backed handlers.

If Yanky is not installed, gui-keymap falls back to Neovim register-based clipboard handling.

`hint_enabled`

Turns hints on or off globally.

`hint_repeat`

Controls how many times a hint can appear for a given shortcut.

0 disables display after zero uses
positive number limits how many times a hint can show
-1 means always show

`hint_persist`

Stores hint counters in Neovim’s state directory so the learning progress does not reset every time Neovim restarts.

`which_key_integration`

If which-key.nvim is available, active mappings are registered with descriptions.

`enforce_on_startup`

Re-applies mappings during startup to handle lazy-loading races from plugin managers and distributions.

`force_priority`

When enabled, gui-keymap can replace conflicting default/editor mappings.

When disabled, conflicting mappings are skipped and reported in diagnostics.

`show_welcome`

Controls the welcome notification shown after first install or after plugin version changes.

`preserve_mode`

For compatible mappings, returns the user to their original mode after the mapped action finishes.

Recommended minimal setup

require("gui-keymap").setup({
  show_welcome = true,
})

Conservative setup

require("gui-keymap").setup({
  shift_selection = false,
  force_priority = false,
  hint_enabled = false,
})

Keymaps and Behavior

GUI shortcut table

Shortcut	Mode	Behavior	Vim equivalent
`Ctrl+C`	normal	copy line	`yy`
`Ctrl+C`	visual	copy selection	`y`
`Ctrl+V`	normal	paste	`p`
`Ctrl+V`	insert	paste	insert paste
`Ctrl+X`	visual	cut selection	`d`
`Ctrl+A`	normal	select all	`ggVG`
`Ctrl+A`	insert	select all	`<Esc>ggVG`
`Ctrl+Z`	normal	undo	`u`
`Ctrl+Z`	insert	undo	`<C-o>u`
`Ctrl+Y`	normal	redo	`<C-r>`
`Ctrl+Y`	insert	redo	`<C-o><C-r>`
`Ctrl+S`	normal	save buffer	`:write`
`Ctrl+S`	insert	save buffer	`:write`
`Ctrl+S`	visual	save buffer	`:write`
`Ctrl+Q`	normal	save and close	`:confirm wq`
`Ctrl+Q`	insert	save and close	`:confirm wq`
`Home`	normal	line start	`0`
`Home`	insert	line start	`<C-o>0`
`Home`	visual	line start	`0`
`End`	normal	line end	`$`
`End`	insert	line end	`<C-o>$`
`End`	visual	line end	`$`
`Ctrl+Backspace`	normal	delete previous word	GUI-style previous-word delete
`Ctrl+Backspace`	insert	delete previous word	GUI-style previous-word delete
`Ctrl+Delete`	normal	delete next word	GUI-style next-word delete
`Ctrl+Delete`	insert	delete next word	GUI-style next-word delete

Delete-selection mappings

Visual mode:

Backspace
Delete

These use the black-hole register so clipboard contents are preserved.

Shift+Arrow selection

Normal mode

Shift+Left
Shift+Right
Shift+Up
Shift+Down

These start visual selection and move in the requested direction.

Visual mode

The same keys extend the current selection.

Insert mode

The same keys leave insert mode, enter visual selection, and move accordingly.

Clipboard behavior

Without Yanky

copy, cut, and paste use Neovim register-based handling
clipboard state is synchronized as safely as possible with + and unnamed registers

With Yanky

clipboard actions prefer Yanky handlers
no hard dependency is created
diagnostics show whether Yanky is installed, loaded, or only available for lazy load