lsp_signature.nvim

Show function signature when you type

• This nvim plugin is made for completion plugins that do not support signature help. Need neovim-0.8+ and enable nvim-lsp. (check neovim-0.5/neovim-0.6/neovim-0.9 branch for earlier version support)

• Inspired by completion-nvim, which does have lots of cool features.

• Fully asynchronous lsp buf request.

• Virtual text available

Golang with markdown

Highlight with "Search"

signature2.mov

Lua

The plugin also re-write the builtin lsp signature allow the parameter highlight

Using virtual text to show the next parameter

Virtual text only mode

(from @fdioguardi)

Multiple signatures

In case some of the languages allow function overload, the plugin will show all available signatures

To switch between the signatures, use select_signature_key

Install:

" dein
dein#add('ray-x/lsp_signature.nvim')

" plug
Plug 'ray-x/lsp_signature.nvim'

" Packer
use {
  "ray-x/lsp_signature.nvim",
}

" Lazy
{
  "ray-x/lsp_signature.nvim",
  event = "VeryLazy",
  opts = {},
  config = function(_, opts) require'lsp_signature'.setup(opts) end
}

Setup / Attach the plugin

In your init.lua, call setup()

local cfg = {…}  -- add your config here
require "lsp_signature".setup(cfg)

Alternatively, call on_attach(cfg, bufnr) when the LSP client attaches to a buffer

e.g. gopls:

local golang_setup = {
  on_attach = function(client, bufnr)
    …
    require "lsp_signature".on_attach(signature_setup, bufnr)  -- Note: add in lsp client on-attach
    …
  end,
  …
}

require'lspconfig'.gopls.setup(golang_setup)

Or use the newer LspAttach autocommands. The following example enables signatures for any attached language server:

vim.api.nvim_create_autocmd("LspAttach", {
  callback = function(args)
    local bufnr = args.buf
    local client = vim.lsp.get_client_by_id(args.data.client_id)
    if vim.tbl_contains({ 'null-ls' }, client.name) then  -- blacklist lsp
      return
    end
    require("lsp_signature").on_attach({
      -- ... setup options here ...
    }, bufnr)
  end,
})

Configure

Floating window borders

If you have a recent enough build of Neovim, you can configure borders in the signature help floating window(Thanks @Gabriel Sanches for the PR):

local example_setup = {
  on_attach = function(client, bufnr)
    …
    require "lsp_signature".on_attach({
      bind = true, -- This is mandatory, otherwise border config won't get registered.
      handler_opts = {
        border = "rounded"
      }
    }, bufnr)
    …
  end,
  …
}

Or:

require'lspconfig'.gopls.setup()
require "lsp_signature".setup({
  bind = true, -- This is mandatory, otherwise border config won't get registered.
  handler_opts = {
    border = "rounded"
  }
})

Keymap

No default keymaps are provided. There are two keymaps available in config:

1. toggle_key: Toggle the signature help window. It manual toggle config.floating_windows on/off
2. select_signature_key: Select the current signature when mulitple signature is avalible.

Customize the keymap in your config:

• To toggle floating windows in Normal mode, you need either define a keymap to vim.lsp.buf.signature_help() or require('lsp_signature').toggle_float_win()

e.g.

    vim.keymap.set({ 'n' }, '<C-k>', function()       require('lsp_signature').toggle_float_win()
    end, { silent = true, noremap = true, desc = 'toggle signature' })

    vim.keymap.set({ 'n' }, '<Leader>k', function()
     vim.lsp.buf.signature_help()
    end, { silent = true, noremap = true, desc = 'toggle signature' })

Full configuration (with default values)

 cfg = {
  debug = false, -- set to true to enable debug logging
  log_path = vim.fn.stdpath("cache") .. "/lsp_signature.log", -- log dir when debug is on
  -- default is  ~/.cache/nvim/lsp_signature.log
  verbose = false, -- show debug line number

  bind = true, -- This is mandatory, otherwise border config won't get registered.
               -- If you want to hook lspsaga or other signature handler, pls set to false
  doc_lines = 10, -- will show two lines of comment/doc(if there are more than two lines in doc, will be truncated);
                 -- set to 0 if you DO NOT want any API comments be shown
                 -- This setting only take effect in insert mode, it does not affect signature help in normal
                 -- mode, 10 by default

  max_height = 12, -- max height of signature floating_window
  max_width = 80, -- max_width of signature floating_window, line will be wrapped if exceed max_width
                  -- the value need >= 40
  wrap = true, -- allow doc/signature text wrap inside floating_window, useful if your lsp return doc/sig is too long
  floating_window = true, -- show hint in a floating window, set to false for virtual text only mode

  floating_window_above_cur_line = true, -- try to place the floating above the current line when possible Note:
  -- will set to true when fully tested, set to false will use whichever side has more space
  -- this setting will be helpful if you do not want the PUM and floating win overlap

  floating_window_off_x = 1, -- adjust float windows x position.
                             -- can be either a number or function
  floating_window_off_y = 0, -- adjust float windows y position. e.g -2 move window up 2 lines; 2 move down 2 lines
                              -- can be either number or function, see examples

  close_timeout = 4000, -- close floating window after ms when laster parameter is entered
  fix_pos = false,  -- set to true, the floating window will not auto-close until finish all parameters
  hint_enable = true, -- virtual hint enable
  hint_prefix = "🐼 ",  -- Panda for parameter, NOTE: for the terminal not support emoji, might crash
  -- or, provide a table with 3 icons
  -- hint_prefix = {
  --     above = "↙ ",  -- when the hint is on the line above the current line
  --     current = "← ",  -- when the hint is on the same line
  --     below = "↖ "  -- when the hint is on the line below the current line
  -- }
  hint_scheme = "String",
  hint_inline = function() return false end,  -- should the hint be inline(nvim 0.10 only)?  default false
  -- return true | 'inline' to show hint inline, return 'eol' to show hint at end of line, return false to disable
  -- return 'right_align' to display hint right aligned in the current line
  hi_parameter = "LspSignatureActiveParameter", -- how your parameter will be highlight
  handler_opts = {
    border = "rounded"   -- double, rounded, single, shadow, none, or a table of borders
  },

  always_trigger = false, -- sometime show signature on new line or in middle of parameter can be confusing, set it to false for #58

  auto_close_after = nil, -- autoclose signature float win after x sec, disabled if nil.
  extra_trigger_chars = {}, -- Array of extra characters that will trigger signature completion, e.g., {"(", ","}
  zindex = 200, -- by default it will be on top of all floating windows, set to <= 50 send it to bottom

  padding = '', -- character to pad on left and right of signature can be ' ', or '|'  etc

  transparency = nil, -- disabled by default, allow floating win transparent value 1~100
  shadow_blend = 36, -- if you using shadow as border use this set the opacity
  shadow_guibg = 'Black', -- if you using shadow as border use this set the color e.g. 'Green' or '#121315'
  timer_interval = 200, -- default timer check interval set to lower value if you want to reduce latency
  toggle_key = nil, -- toggle signature on and off in insert mode,  e.g. toggle_key = '<M-x>'
  toggle_key_flip_floatwin_setting = false, -- true: toggle floating_windows: true|false setting after toggle key pressed
     -- false: floating_windows setup will not change, toggle_key will pop up signature helper, but signature
     -- may not popup when typing depends on floating_window setting

  select_signature_key = nil, -- cycle to next signature, e.g. '<M-n>' function overloading
  move_cursor_key = nil, -- imap, use nvim_set_current_win to move cursor between current win and floating window
  -- e.g. move_cursor_key = '<M-p>',
  -- once moved to floating window, you can use <M-d>, <M-u> to move cursor up and down
  keymaps = {}  -- relate to move_cursor_key; the keymaps inside floating window
  -- e.g. keymaps = { 'j', '<C-o>j' } this map j to <C-o>j in floating window
  -- <M-d> and <M-u> are default keymaps to move cursor up and down
}

-- recommended:
require'lsp_signature'.setup(cfg) -- no need to specify bufnr if you don't use toggle_key

-- You can also do this inside lsp on_attach
-- note: on_attach deprecated
require'lsp_signature'.on_attach(cfg, bufnr) -- no need to specify bufnr if you don't use toggle_key

Signature in status line

Sample config

API

require("lsp_signature").status_line(max_width)

return a table

{
  label = 'func fun_name(arg1, arg2…)'
  hint = 'arg1',
  range = {start = 13, ['end'] = 17 }
  doc = 'func_name return arg1 + arg2 …'
}

In your statusline or winbar

local current_signature = function(width)
  if not pcall(require, 'lsp_signature') then return end
  local sig = require("lsp_signature").status_line(width)
  return sig.label .. "🐼" .. sig.hint
end

set floating windows position based on cursor position

-- cfg = {…}  -- add you config here
local cfg = {
  floating_window_off_x = 5, -- adjust float windows x position.
  floating_window_off_y = function() -- adjust float windows y position. e.g. set to -2 can make floating window move up 2 lines
    local linenr = vim.api.nvim_win_get_cursor(0)[1] -- buf line number
    local pumheight = vim.o.pumheight
    local winline = vim.fn.winline() -- line number in the window
    local winheight = vim.fn.winheight(0)

    -- window top
    if winline - 1 < pumheight then
      return pumheight
    end

    -- window bottom
    if winheight - winline < pumheight then
      return -pumheight
    end
    return 0
  end,
}
require "lsp_signature".setup(cfg)

Should signature floating windows fixed

fix_pos can be a function, it took two element, first is the signature result for your signature, second is lsp client.

You can provide a function.

e.g.

fix_pos = function(signatures, lspclient)
   if signatures[1].activeParameter >= 0 and #signatures[1].parameters == 1 then
     return false
   end
   if lspclient.name == 'sumneko_lua' then
     return true
   end
   return false
end

Sample config with cmp, luasnipet and autopair

init.lua

Q&A:

Q: What is the default colorscheme in screenshot:

A: aurora

Q: I can not see border after enable border = "single"/"rounded"

A: Try another colorscheme (e.g. colorscheme aurora, or colorscheme luna). If issue persists, please submit an issue

Q: It is not working 😡

A: Here is some trouble shooting: ray-x#1

If you are using JDTLS, please read this: issue #97

Q:I do not like the pop window background highlight, how to change it?

A: Redefine your NormalFloat and FloatBorder, esp if your colorscheme dose not define it.

Q: How to change parameter highlight

A: By default, the highlight is using "LspSignatureActiveParameter" defined in your colorscheme, you can either override "LspSignatureActiveParameter" or define, e.g. use IncSearch setup({ hi_parameter = "IncSearch"})

Q: I can not see 🐼 in virtual text

A: It is emoji, not nerdfont. Please check how to enable emoji for your terminal.

Q: Working with cmp/coq. The floating windows block cmp/coq

A: A few options here, z-index, floating_window_above_cur_line, floating_window_off_x/y, toggle_key. You can find the best setup for your workflow.