Skip to main content

​
Changing the default leader key

Better Vim uses the Space key as the default leader. If you want to change it, you can use the better-vim.lua file. To change your leader from Space to , you can update your better-vim.lua to something like:
better-vim.lua
return {
  mappings = {
    leader = ",",
  },
}

​
Creating your own mappings

There are two ways to create your own custom mappings:
  • Using the whichkey.nvim plugin + the Better Vim modules;
  • Using lua and hooks.after_setup hook in better-vim.lua.

​
Creating mappings with whichkey

To create your own mappings using the whichkey plugin you’ll use the better-vim.lua module. Let’s see how to create a mapping to open the file explorer using ctrl + b:
better-vim.lua
return {
  mappings = {
    custom = {
    ["<c-b>"] = {
       "<cmd>NvimTreeToggle<cr>",
       "Open file explorer",
      },
    },
  },
}
We can split the mapping creation into 3 parts:
    1. On the line 4 we define the combination of keys that we want to use
    1. On the line 5 we set the command that we want to execute
    1. And on the line 6 we set a description for this mapping
📢 Since we’re using whichkey.nvim to create custom mappings, you may want to check its official documentation before creating your own mappings.

​
Creating mappings by mode

You can also create your own mappings by mode. This is important if you have the same shortcuts, but want different commands for different modes:
better-vim.lua
return {
  mappings = {
    by_mode = {
      i = {}, -- use these tables to create your mapings
      v = {}, -- ┙
    },
  },
}
You can use i (for insert mode), n (for normal mode), v (for visual and select modes) or x (for only visual mode). The options are the same as used in mappings.custom.

​
Creating mappings for tabs

You can create custom mappings to change tabs. The default mapping is alt/option + tab number. To customize it, just pass a function to the tabs key inside mappings table. The function receives the tab number. That way you just concatenate the tab number with your custom keys:
better-vim.lua
return {
  mappings = {
  tabs = function(tab)
    return "<leader>h" .. tab
  end,
  }
}
The example above will create the mappings: 
<leader>h1 -> first tab
<leader>h2 -> second tab
...
<leader>h20 -> twentyth tab
Now, you can use <leader>h1 to go to tab 1, instead of alt + 1.

​
Creating mappings with lua

To create custom mappings using lua you can use the hooks.after_setup entry in better-vim.lua file, following this tutorial from the Neovim official documentation.

​
Custom mappings for autocomplete (cmp)

You can customize your mappings for autocomplete (nvim-cmp) using lua, just use the cmp entry in your configuration. Check out the example below with defaults:
better-vim.lua
return {
  cmp = {
    mappings = {
      scroll_docs_down = "<C-d>",
      scroll_docs_up = "<C-u>",
      next_item = "<C-n>",
      prev_item = "<C-p>",
      show_list = "<C-Space>",
      confirm = "<CR>",
    },
    before_default_sources = {},
    after_default_sources = {},
  }
}
The before_default_sources and after_default_sources options can be used to load nvim-cmp plugins before and after the default sources that is already installed with Better Vim. If you want to know more about nvim-cmp sources, check out the plugin documentation.