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,
})

gui-keymap.nvim