How do I programmatically remove or unmap a keybinding in Neovim Lua without knowing its original definition?

Explanation

vim.keymap.del(mode, lhs, opts) removes an existing keymap from Neovim's keymap table. This is essential when you want to clear a default Neovim mapping, override a plugin's keymap with nothing, or conditionally unmap keys based on filetype — without having to know or reproduce the original binding's rhs.

How it works

• mode — the mode(s) to remove the mapping from: 'n', 'i', 'v', etc.
• lhs — the key sequence to unmap, e.g. 'grn' or '<C-k>'
• opts — optional table, currently supports buffer to remove a buffer-local mapping

-- Remove a global mapping
vim.keymap.del('n', 'grn')

-- Remove a buffer-local mapping
vim.keymap.del('n', 'K', { buffer = 0 })

-- Remove multiple modes at once
vim.keymap.del({ 'n', 'v' }, '<C-k>')

Example

Neovim 0.11 ships default LSP keymaps like grn (rename), gra (code action), grr (references). To remove the ones you prefer to define yourself:

vim.api.nvim_create_autocmd('LspAttach', {
  callback = function(args)
    -- Remove Neovim defaults and replace with your own
    vim.keymap.del('n', 'grn', { buffer = args.buf })
    vim.keymap.set('n', '<leader>rn', vim.lsp.buf.rename, { buffer = args.buf })
  end,
})

Tips

• vim.keymap.del silently fails if the mapping does not exist — wrap in pcall() if you need to handle the error
• To inspect whether a mapping exists before deleting, use vim.fn.maparg(lhs, mode, false, true)
• For Vimscript the equivalent is :unmap {lhs} / :nunmap {lhs}