std-enigma / mapper.nvim

A different approach to set NeoVim key mappings

⌨️ Mapper

An alternative solution to setup your neovim key mappings.

⚡️ Requirements

• Neovim >= 0.5.0

⚠️ Caution

which-key.nvim registration isn't possible if you are using any package manager rather than lazy.nvim

📦 Installation

Install the plugin with your preferred package manager:

lazy.nvim

{
  "Std-Enigma/mapper.nvim",
  opts = {}, -- for setting up your mappings, refer to the usage section.
}

💡 API

Mapper provides a Lua API with key mapping functionality. This can be viewed with :h mapper or in the repository at doc/api.md

🚀 Usage

Lazy Plugin

Lazy

{
  "Std-Enigma/mapper.nvim",
  opts = {
    mappings = {
      -- map mode (:h map-modes)
      n = {
        ["<C-s>"] = { ":w!<cr>", desc = "Save File" }, -- use vimscript strings for mappings
        L = {
          function() vim.cmd.bnext() end, -- use lua functions for mappings
          desc = "Next buffer",
        },
        H = {
          function() vim.cmd.bprevious() end, -- use lua functions for mappings
          desc = "Previous buffer",
        },
        -- tables with just a `desc` key will be registered with which-key if it's installed
        -- this is useful for naming menus
        ["<leader>b"] = { desc = "Buffers" },
      },
    },
  },
}

Usage with other plugins

{
  "mrjones2014/smart-splits.nvim",
  dependencies = {
    {
      "Std-Enigma/mapper.nvim",
      opts = function(_, _)
        local maps = require("mapper").empty_map_table()
        maps.n["<C-H>"] = { function() require("smart-splits").move_cursor_left() end, desc = "Move to left split" }
        maps.n["<C-J>"] = { function() require("smart-splits").move_cursor_down() end, desc = "Move to below split" }
        maps.n["<C-K>"] = { function() require("smart-splits").move_cursor_up() end, desc = "Move to above split" }
        maps.n["<C-L>"] = { function() require("smart-splits").move_cursor_right() end, desc = "Move to right split" }
        maps.n["<C-Up>"] = { function() require("smart-splits").resize_up() end, desc = "Resize split up" }
        maps.n["<C-Down>"] = { function() require("smart-splits").resize_down() end, desc = "Resize split down" }
        maps.n["<C-Left>"] = { function() require("smart-splits").resize_left() end, desc = "Resize split left" }
        maps.n["<C-Right>"] = { function() require("smart-splits").resize_right() end, desc = "Resize split right" }
	return { mappings = maps } -- we do this so lazy.nvim can merge your mappings table
      end,
    },
  },
  opts = {},
}

Lua API

API

You can setup your mappings like so with the api:

local mapper = require("mapper")
local mappings = mapper.empty_map_table()

-- tables with just a `desc` key will be registered with which-key if it's installed
-- this is useful for naming menus
mappings.n["<Leader>b"] = { desc = "Buffers" }
mappings.n["L"] = { function() vim.cmd.bnext() end, desc = "Next buffer" } -- use lua functions for mappings
mappings.n["H"] = { function() vim.cmd.bprevious() end, desc = "Previous buffer" } -- use lua functions for mappings
mappings.n["<C-S>"] = { "<Cmd>silent! update! | redraw<CR>", desc = "Force write" } -- use vimscript strings for mappings
maps.i["<C-S>"] = { "<Esc>" .. maps.n["<C-S>"][1], desc = maps.n["<C-S>"].desc } -- you can use already defined mappings properties since this is just a lua table

mapper.set_mappings(mappings)

⭐ Credits

This plugin is a direct implementation of AstroNvim core utilities for setting up key mappings.