configuration

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:

1. saves pending changes
2. 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,
})