From c44df255aa095525647efaeaba2bc41ed1d538f5 Mon Sep 17 00:00:00 2001
From: Evgeni Chasnovski <evgeni.chasnovski@gmail.com>
Date: Sat, 25 Apr 2026 20:03:55 +0300
Subject: [PATCH] docs(vim.ui): "preview" interface for vim.ui.select() #37360

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.
---
 runtime/doc/lua.txt    | 19 +++++++++++++++++++
 runtime/lua/vim/ui.lua | 17 +++++++++++++++++
 2 files changed, 36 insertions(+)

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index c508410de3..6b0e57ee78 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -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
diff --git a/runtime/lua/vim/ui.lua b/runtime/lua/vim/ui.lua
index fe670893e5..89133697b3 100644
--- a/runtime/lua/vim/ui.lua
+++ b/runtime/lua/vim/ui.lua
@@ -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))