vim.ui

Methods6

function M.select<T>(items: T[], opts: vim.ui.select.Opts, on_choice: fun(item: T | nil, idx: nil | integer) -> nil) -> nil

Prompts the user to pick from a list of items, allowing arbitrary (potentially asynchronous) work until on_choice. This is the standard "picker" interface, used by |z=|, |:tselect|, etc.

Plugins may override vim.ui.select to provide a custom picker; they are expected to call the format_item and preview_item handlers (if any) provided by the caller. They may also use the kind hint (if provided by the caller) to decide how to handle some items.

Note: the default vim.ui.select currently doesn't support preview.

Example:

vim.ui.select({ 'tabs', 'spaces' }, {
  prompt = 'Select tabs or spaces:',
  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))
end)

Parameters

itemsT[]: Arbitrary items
optsvim.ui.select.Opts: Options
on_choicefun(item: T | nil, idx: nil | integer) -> nil: Called once the user made a choice. idx is the 1-based index of item within items, or nil if the user aborted the dialog.

Returns

nil

function M.input(opts: vim.ui.input.Opts | nil, on_confirm: fun(input: nil | string) -> nil) -> nil

Prompts the user for input, allowing arbitrary (potentially asynchronous) work until on_confirm.

Example:

local opts = { prompt = 'Enter value for shiftwidth: ', scope = 'buffer' }
vim.ui.input(opts, function(input)
    vim.o.shiftwidth = tonumber(input)
end)

Parameters

optsvim.ui.input.Opts | nil: Additional options. See |input()|
on_confirmfun(input: nil | string) -> nil

Returns

nil

function M.open(path: string, opt: vim.ui.open.Opts | nil) -> (vim.SystemObj | nil, nil | string)

Opens path with the system default handler (macOS open, Windows explorer.exe, Linux xdg-open, …), or returns (but does not show) an error message on failure.

Can also be invoked with :Open. :Open

Expands "~/" and environment variables in filesystem paths.

Examples:

-- Asynchronous.
vim.ui.open("https://neovim.io/")
vim.ui.open("~/path/to/file")
-- Use the "osurl" command to handle the path or URL.
vim.ui.open("gh#neovim/neovim!29490", { cmd = { 'osurl' } })
-- Synchronous (wait until the process exits).
local cmd, err = vim.ui.open("$VIMRUNTIME")
if cmd then
  cmd:wait()
end

Parameters

pathstring: Path or URL to open
optvim.ui.open.Opts | nil: Options

Returns

vim.SystemObj | nil: Command object, or nil if not found.
nil | string: Error message on failure, or nil on success.

See:

|vim.system()|

function M._get_open_cmd() -> (string[] | nil, nil | string)

Get an available command used to open the path or URL.

Returns

string[] | nil: Command, or nil if not found.
nil | string: Error message on failure, or nil on success.

function M._get_urls() -> string[]

Returns all URLs at cursor, if any.

function M.progress_status() -> string

Gets a status description summarizing currently running progress messages. Convenient for inclusion in 'statusline'.

Returns

string: Progress status

Fields1

M.img : vim.ui.img