mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2026-05-23 21:30:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(vim.ui): "preview" interface for vim.ui.select() #37360

Browse Source 
Problem: Plugins may want to have a way to show more details about items
  when using `vim.ui.select`. This is a fairly common problem that
  prompts plugin authors to implement dedicated sources/pickers for
  fuzzy picker plugins that are popular at the moment.

Solution: Document a way for `vim.ui.select` to provide preview:
  - `vim.ui.select` users can provide `opts.preview_item` function that
    creates/uses a buffer and its contents at certain position to show
    more details about an item.
  - `vim.ui.select` implementations may use `opts.preview_item` in the
    way they see fit (like show the buffer in a separate/same window
    interactively/on-demand or do nothing) if they have a way to show
    more information about an item.
This commit is contained in:
Evgeni Chasnovski
2026-04-25 20:03:55 +03:00
committed by GitHub
parent 775c7d1b53
commit c44df255aa
2 changed files with 36 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
runtime/doc/lua.txt
View File

@@ -5181,6 +5181,13 @@ vim.ui.select({items}, {opts}, {on_choice}) *vim.ui.select()*
format_item = function(item)
return ('I choose %s!'):format(item)
end,
preview_item = function(item)
local lines = { 'This is ' .. vim.inspect(item) }
local buf = vim.api.nvim_create_buf(false, true)
vim.api.nvim_buf_set_lines(buf, 0, -1, false, lines)
vim.bo[buf].bufhidden = 'wipe'
return { buf = buf }
end,
}, function(choice)
vim.o.expandtab = choice == 'spaces'
vim.print(('Selected "%s" => expandtab=%s'):format(choice, vim.o.expandtab))
@@ -5195,6 +5202,18 @@ vim.ui.select({items}, {opts}, {on_choice}) *vim.ui.select()*
• {format_item}? (`fun(item: any):string`) Function to
format an individual item from `items`. Defaults to
`tostring`.
• {preview_item}? (`fun(item: any):table`) Function to
preview an individual item from `items`. If missing, no
special preview is used. Should ensure a buffer with
contents (text, highlighting) providing details about
an item. Should return a table with information that
`vim.ui.select` implementations may use to show the
preview buffer in the way they see fit:
• {buf}? (`integer`) - buffer id with preview. If
missing, no preview should be shown.
• {pos}? (`[integer, integer]`) - (1,0)-indexed tuple
of where to position cursor in the preview buffer. If
missing, should be treated as `{ 1, 0 }`.
• {kind}? (`string`) Arbitrary hint string indicating the
item shape. Plugins reimplementing `vim.ui.select` may
wish to use this to infer the structure or semantics of

17
runtime/lua/vim/ui.lua
View File

@@ -10,6 +10,16 @@ local M = {}
--- individual item from `items`. Defaults to `tostring`.
---@field format_item? fun(item: any):string
---
--- Function to preview an individual item from `items`.
--- If missing, no special preview is used.
--- Should ensure a buffer with contents (text, highlighting) providing details about an item.
--- Should return a table with information that `vim.ui.select` implementations may
--- use to show the preview buffer in the way they see fit:
--- - {buf}? (`integer`) - buffer id with preview. If missing, no preview should be shown.
--- - {pos}? (`[integer, integer]`) - (1,0)-indexed tuple of where to position cursor
--- in the preview buffer. If missing, should be treated as `{ 1, 0 }`.
---@field preview_item? fun(item: any):table
---
--- Arbitrary hint string indicating the item shape.
--- Plugins reimplementing `vim.ui.select` may wish to
--- use this to infer the structure or semantics of
@@ -27,6 +37,13 @@ local M = {}
--- format_item = function(item)
--- return ('I choose %s!'):format(item)
--- end,
--- preview_item = function(item)
--- local lines = { 'This is ' .. vim.inspect(item) }
--- local buf = vim.api.nvim_create_buf(false, true)
--- vim.api.nvim_buf_set_lines(buf, 0, -1, false, lines)
--- vim.bo[buf].bufhidden = 'wipe'
--- return { buf = buf }
--- end,
--- }, function(choice)
--- vim.o.expandtab = choice == 'spaces'
--- vim.print(('Selected "%s" => expandtab=%s'):format(choice, vim.o.expandtab))