Customize Mappings

Mappings can be customized through AstroCore and AstroLSP. AstroCore handles the general mappings that are applied to the editor where AstroLSP handles mappings that are set when a language server attaches. This page goes over how to customize these mappings to fit your needs.

Add Custom Mappings

These tables are a direct conversion to the vim.keymap.set({mode}, {lhs}, {rhs}, {opts}) Lua API. The first key into the table is the {mode}, the second key into the table is the {lhs}, and the element there is the {opts} table with the {rhs} in the first key. Also AstroLSP supports adding a cond key which can dictate when the mapping should be attached (this is described in detail in the AstroLSP plugin configuration documentation) Here is a simple plugin specification example of setting both core and LSP mappings:

return {
  {
    "AstroNvim/astrocore",
    ---@type AstroCoreOpts
    opts = {
      mappings = {
        -- first key is the mode
        n = {
          -- second key is the lefthand side of the map
          -- mappings seen under group name "Buffer"
          ["<Leader>bn"] = { "<cmd>tabnew<cr>", desc = "New tab" },
          ["<Leader>bD"] = {
            function()
              require("astroui.status").heirline.buffer_picker(function(bufnr)
                require("astrocore.buffer").close(bufnr)
              end)
            end,
            desc = "Pick to close",
          },
          -- 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" },
          -- quick save
          -- ["<C-s>"] = { ":w!<cr>", desc = "Save File" },  -- change description but the same command
        },
        t = {
          -- setting a mapping to false will disable it
          -- ["<esc>"] = false,
        },
      },
    },
  },
  {
    "AstroNvim/astrolsp",
    ---@type AstroLSPOpts
    opts = {
      mappings = {
        n = {
          -- this mapping will only be set in buffers with an LSP attached
          K = {
            function()
              vim.lsp.buf.hover()
            end,
            desc = "Hover symbol details",
          },
          -- condition for only server with declaration capabilities
          gD = {
            function()
              vim.lsp.buf.declaration()
            end,
            desc = "Declaration of current symbol",
            cond = "textDocument/declaration",
          },
        },
      },
    },
  },
}

Enable Telescope LSP Mappings

Telescope provides functionality for using the picker for tasks such as getting references and symbols. This can be easily enabled through AstroLSP. Here is an example specification that can be added to your plugins:

return {
  "AstroNvim/astrolsp",
  ---@param opts AstroLSPOpts
  opts = function(_, opts)
    if opts.mappings.n.gd then
      opts.mappings.n.gd[1] = function()
        require("telescope.builtin").lsp_definitions({ reuse_win = true })
      end
    end
    if opts.mappings.n.gI then
      opts.mappings.n.gI[1] = function()
        require("telescope.builtin").lsp_implementations({ reuse_win = true })
      end
    end
    if opts.mappings.n.gy then
      opts.mappings.n.gy[1] = function()
        require("telescope.builtin").lsp_type_definitions({ reuse_win = true })
      end
    end
    if opts.mappings.n["<Leader>lG"] then
      opts.mappings.n["<Leader>lG"][1] = function()
        vim.ui.input(
          { prompt = "Symbol Query: (leave empty for word under cursor)" },
          function(query)
            if query then
              -- word under cursor if given query is empty
              if query == "" then
                query = vim.fn.expand("<cword>")
              end
              require("telescope.builtin").lsp_workspace_symbols({
                query = query,
                prompt_title = ("Find word (%s)"):format(query),
              })
            end
          end
        )
      end
    end
    if opts.mappings.n["<Leader>lR"] then
      opts.mappings.n["<Leader>lR"][1] = function()
        require("telescope.builtin").lsp_references()
      end
    end
  end,
}