hover.nvim

repository·main·Indexed 20 days ago

A general framework for context-aware hover providers in Neovim (v0.11.0+). It extends built-in LSP hover functionality to support other sources including diagnostics, DAP, man pages, GitHub issues, and Jira. It features a configurable provider system with priority management, mouse hover support, and an API for implementing custom Hover.Provider and Hover.ProviderGroup objects.

Tokens: 1.9K
Snippets: 5
Records: 8
Agent score: 23%

What's inside hover.nvim

Set up keymaps for hover.nvim

main

To interact with hover.nvim, you should map the following API functions to your preferred keys:

require('hover').open(): Opens the hover window.
require('hover').enter(): Enters the hover window.
require('hover').switch('previous'): Switches to the previous provider source.
require('hover').switch('next'): Switches to the next provider source.
require('hover').mouse(): Triggers hover via mouse movement (requires vim.o.mousemoveevent = true).

-- Setup keymaps
vim.keymap.set('n', 'K', function()
  require('hover').open()
end, { desc = 'hover.nvim (open)' })

vim.keymap.set('n', 'gK', function()
  require('hover').enter()
end, { desc = 'hover.nvim (enter)' })

vim.keymap.set('n', '<C-p>', function()
    require('hover').switch('previous')
end, { desc = 'hover.nvim (previous source)' })

vim.keymap.set('n', '<C-n>', function()
    require('hover').switch('next')
end, { desc = 'hover.nvim (next source)' })

-- Mouse support
vim.keymap.set('n', '<MouseMove>', function()
  require('hover').mouse()
end, { desc = 'hover.nvim (mouse)' })

vim.o.mousemoveevent = true

Install and Configure hover.nvim
main
To use hover.nvim, ensure you are running Neovim v0.11.0 or higher. Use require('hover').config() to define your providers and appearance settings.
Key configuration options include:
- providers: A list of module names (strings) or provider objects to load.
- preview_opts: Table for window options (e.g., border = 'single').
- preview_window: Boolean; if true, moves the current hover window to a :h preview-window when the hover keymap is pressed.
- title: Boolean; whether to show the title.
- mouse_providers: List of modules enabled for mouse hover support.
- mouse_delay: Delay in milliseconds for mouse hover.
```
require('hover').config({
  providers = {
    'hover.providers.diagnostic',
    'hover.providers.lsp',
    'hover.providers.dap',
    'hover.providers.man',
    'hover.providers.dictionary',
  },
  preview_opts = {
    border = 'single'
  },
  preview_window = false,
  title = true,
  mouse_providers = {
    'hover.providers.lsp',
  },
  mouse_delay = 1000
})
```
https://github.com/lewis6991/hover.nvim/blob/main/README.md
Customize provider priority and names
main
Instead of using a string in the providers list, you can pass a table to customize a provider's priority and name. This is only supported for providers created via passive registration.
```
require('hover').config({
  providers = {
    {
      module = 'hover.providers.diagnostic',
      priority = 2000,
      name = 'Diags'
    }
  }
})
```
https://github.com/lewis6991/hover.nvim/blob/main/README.md

Implement a Hover.ProviderGroup

main

If you want to group multiple providers together, return a Hover.ProviderGroup object from your module. This allows you to manage a collection of providers as a single unit. The group can have its own priority which overrides individual provider priorities.

-- In myplugin/simple_provider.lua
local simple_provider = {
  name = 'Simple',
  enabled = function(bufnr)
    return true
  end,
  execute = function(params, done)
    done{lines={'TEST'}, filetype="markdown"}
  end
}

return {
   priority = 1000,
   providers = { simple_provider }
}

-- In your config
require('hover').config({
    providers = {
        'myplugin.simple_provider'
    }
})

Implement a custom Hover.Provider
main
To create a new provider, create a module in your runtimepath that returns a Hover.Provider object.
An implementation must include:
- name: A string identifier.
- priority: An integer.
- enabled: A function (bufnr) -> boolean to determine if the provider is active in the current buffer.
- execute: A function (params, done) -> nil that performs the logic and calls done with a Hover.Result.
```
-- In myplugin/simple_provider.lua
return {
   name = 'Simple',
   priority = 1000,
   enabled = function(bufnr)
     return true
   end,
   execute = function(params, done)
     done{lines={'TEST'}, filetype="markdown"}
   end
}

-- In your config
require('hover').config({
    providers = {
        'myplugin.simple_provider'
    }
})
```
https://github.com/lewis6991/hover.nvim/blob/main/README.md
Hover.Provider API Reference
main
Hover.Provider
- name: string
- priority?: integer
- enabled?: function(bufnr: integer, opts?: Hover.Options): boolean
- execute: function(params: Hover.Provider.Params, done: fun(result?: false|Hover.Result))
Hover.Provider.Params
- bufnr: integer
- pos: [integer, integer]
Hover.Result
- lines?: string[]
- filetype?: string
- bufnr?: integer (Use a pre-populated buffer; lines will be ignored)
https://github.com/lewis6991/hover.nvim/blob/main/README.md
Reference of built-in hover providers
main
The following providers are built into hover.nvim:
- hover.providers.lsp (Priority 1000): Supports multiple LSP clients.
- hover.providers.diagnostic (Priority 1001): Uses vim.diagnostic.
- hover.providers.dap (Priority 1002): Uses nvim-dap.
- hover.providers.fold_preview (Priority 1003): Previews closed folds under the cursor.
- hover.providers.gh (Priority 200): Opens GitHub issues/PRs for symbols like #123. Requires gh CLI.
- hover.providers.gh_user (Priority 200): GitHub user info in TODO comments. Requires gh CLI.
- hover.providers.jira (Priority 175): Opens Jira issues (e.g., ABC-123). Requires jira CLI.
- hover.providers.man (Priority 150): Man pages.
- hover.providers.dictionary (Priority 100): Word definitions.
- hover.providers.highlight: Preview highlight groups using vim.inspect_pos.
https://github.com/lewis6991/hover.nvim/blob/main/README.md

Customize hover window appearance

main

You can customize the look of the hover window by overriding the following highlight groups:

Group	Default	Description
`HoverWindow`	`NormalFloat`	Main window background
`HoverBorder`	`FloatBorder`	Window border
`HoverSourceLine`	`TabLine`	The line showing the source
`HoverActiveSource`	`TabLineSel`	The currently active source
`HoverInactiveSource`	`TabLineFill`	Inactive sources
`HoverFloatingError`	`DiagnosticFloatingError`
`HoverFloatingWarn`	`DiagnosticFloatingWarn`
`HoverFloatingInfo`	`DiagnosticFloatingInfo`
`HoverFloatingHint`	`DiagnosticFloatingHint`

hover.nvim

What's inside hover.nvim

Hover.Provider

Hover.Provider.Params

Hover.Result