*mini.input* Get user input

MIT License Copyright (c) 2026 Evgeni Chasnovski

------------------------------------------------------------------------------

*MiniInput*

Features:

- Get user input with fully customizable key and view handling.

- Built-in configurable views as floating window, statusline/tabline/winbar,

virtual line/text.

- Implementation is non-blocking but waits to return the input. It also works

in any mode without requiring mode change. See |MiniInput-lifecycle|.

- |vim.ui.input()| implementation. To adjust, use |MiniInput.ui_input()| or

save-restore `vim.ui.input` manually after calling |MiniInput.setup()|.

Sources with more details:

- |MiniInput.get()|

- |MiniInput.default_key()|

- |MiniInput-state|

- |MiniInput-examples|

- |MiniInput-in-other-plugins| (for plugin authors)

# Setup ~

This module needs a setup with `require('mini.input').setup({})` (replace `{}`

with your `config` table). It will create global Lua table `MiniInput` which

you can use for scripting or manually (with `:lua MiniInput.*`).

See |MiniInput.config| for `config` structure and default values.

You can override runtime config settings locally to buffer inside

`vim.b.miniinput_config` which should have same structure as

`MiniInput.config`. See |mini.nvim-buffer-local-config| for more details.

# Comparisons ~

- [folke/snacks.nvim#input](https://github.com/folke/snacks.nvim):

- Both provide |vim.ui.input()| implementation.

- Has asynchronous implementation (i.e. does not wait for user to finish

input), while this module has synchronous non-blocking implementation.

- Uses floating window and forced Insert mode. This module allows more

view customizations and can be used in any mode without interruptions.

- |input()|:

- Both are synchronous.

- Both allow custom highlight and completion.

- This module also allows supplying input scope and visibility,

customizing keys and view.

# Highlight groups ~

*MiniInput-hl-groups*

- `MiniInputAdded` - added text during completion navigation.

- `MiniInputBorder` - border of a |MiniInput.gen_view.floatwin()| handler.

- `MiniInputCaret` - caret symbol shown in a prompt area.

- `MiniInputHide` - input is hidden, usually used instead of `MiniInputPrompt`.

- `MiniInputHint` - hints shown during completion navigation.

- `MiniInputNormal` - basic foreground/background.

- `MiniInputPrompt` - input prompt (intention of the input).

- `MiniInputSpecial` - special keys (like literal `\t`, `\n`, etc.) in input.

# Using in other plugins ~

*MiniInput-in-other-plugins*

- Prefer using |vim.ui.input()| for more user coverage. Use |MiniInput.get()|

only when getting input synchronously is absolutely necessary.

- Perform a `_G.MiniInput ~= nil` check before using any feature. This ensures

that user explicitly set up the module.

------------------------------------------------------------------------------

*MiniInput-state*

Information about the state of the input. It is passed as a handler argument.

Use |MiniInput.get_state()| to get information about the current state (if any).

A table with the following fields:

- <caret> `(number)` - character (not byte) index at which to modify input.

Should be from 1 (prepend input) to "input width plus 1" (append input).

- <complete> `(table|nil)` - information about active completion navigation.

If present, it means that completion navigation is in action.

Its fields describe the state of navigation:

- <base> `(string)` - reference text to the left of caret at the start

of completion. Used to compute candidates. Can be empty string.

- <id> `(number)` - identifier of current completion item. Can be zero to

mean that the base is shown. If not zero, must mean that a `items[id]`

candidate is now shown to the left of caret as the part of the input.

- <items> `(table)` - string array of completion candidates. May be empty.

Are intended to fully replace <base>, so should contain it in any sense.

- <method> `(string)` - completion method. Like `"default"`, `"history"`, etc.

Can be `""` (empty string) to mean "default method of complete handler".

- <data> `(table)` - any information to be reused within the same input session.

Note: handlers should not change fields that they don't "own".

- <errmsg> `(errmsg)` - first error message caught during input process.

- <highlight> `(table|nil)` - information about current input highlighting.

If absent, the whole input is highlighted using `MiniInputNormal` group.

Should be an array of highlight ranges. They might be not ordered, overlap,

go outside of input width. It is up to the view handler to decide how to

interpret them. See |MiniInput.state_to_chunks()| for a helper.

Fields of a single highlight range:

- <from> `(number)` - character index (one-indexed) of range start.

- <to> `(number)` - character index (one-indexed) of range end (inclusive).

Should not be smaller than <from>. Can be |math.huge|.

- <hl> `(string)` - highlight group to use for highlighting.

- <input> `(string)` - current user input. Returned by |MiniInput.get()|.

- <opts> `(table)` - input options, same as in |MiniInput.get()|.

- <prompt> `(string)` - intention of the input. May be empty.

- <status> `(string)` - one of `"start"`, `"progress"`, `"accept"`, `"cancel"`.

------------------------------------------------------------------------------

*MiniInput-examples*

# General ~

## Initial input ~

Use `opts.init_keys` to imitate the initial state of the input: >lua

MiniInput.get({ init_keys = { 'Default' } })

<

## Custom mappings ~

Override `handlers.key` in |MiniInput.config|: >lua

local key_handler = function(state, key)

-- <C-a> - move caret to start of line

if key == '\1' then

state.caret = 1

-- <S-BS> - clear all input

elseif key == vim.keycode('<S-BS>') then

state.input, state.caret = '', 1

else

-- IMPORTANT: Fall back to processing as usual

return MiniInput.default_key(state, key)

end

end

require('mini.input').setup({ handlers = { key = key_handler } })

<

## Basic command line ~

An alternative |Command-line| with highlighting and completion: >lua

-- Construct reusable `MiniInput.get()` options

local cmdline_opts = { prompt = 'Command', scope = 'editor' }

-- - Highlight using bundled Vim tree-sitter parser and default handler

local highlight_vim = MiniInput.gen_highlight.treesitter('vim')

local highlight_cmdline = function(state)

state = highlight_vim(state) or state

return MiniInput.default_highlight(state) or state

end

cmdline_opts.handlers = { highlight = highlight_cmdline }

-- - Complete as if it is Command line input

cmdline_opts.completion = 'cmdline'

-- Create a mapping for `:`

local input_cmdline = function()

local cmd = MiniInput.get(cmdline_opts)

if cmd ~= nil then vim.cmd(cmd) end

end

vim.keymap.set('n', ':', input_cmdline)

<

# Handlers ~

## Key ~

Perform custom actions based on arbitrary conditions: >lua

local key_handler = function(state, key)

-- Adjust prompt

state.opts.prompt = state.opts.prompt:gsub('[?:]%s*$', '')

-- Adjust scope

if state.opts.prompt == 'Editor action' then

state.opts.scope = 'editor'

end

-- Hide from view and history

if state.opts.prompt:find('[Pp]assword') ~= nil then

state.opts.hide = true

end

-- IMPORTANT: Process as usual

state = MiniInput.default_key(state, key) or state

-- Auto fill and accept

if state.input == 'AF' then

state.input, state.status = 'Autofilled input', 'accept'

end

end

require('mini.input').setup({ handlers = { key = key_handler } })

<

## View ~

Show no view: >lua

require('mini.input').setup({ handlers = { view = function() end } })

<

Compute initial style depending on scope: >lua

local input = require('mini.input')

local view_virtline = input.gen_view.virtual({ style = 'above' })

local view_tabline = input.gen_view.uiline({ style = 'tabline' })

local view_winbar = input.gen_view.uiline({ style = 'winbar' })

local view_handler = function(state)

-- NOTE: does not support interactive scope change

local scope, view = state.opts.scope, view_tabline

if scope == 'buffer' or scope == 'window' then view = view_winbar end

if scope == 'cursor' or scope == 'line' then view = view_virtline end

return view(state)

end

input.setup({ handlers = { view = view_handler } })

<

Change symbols for caret and hidden input: see |MiniInput.gen_view|.

------------------------------------------------------------------------------

*MiniInput.setup()*

`MiniInput.setup`({config})

Module setup

Parameters ~

{config} `(table|nil)` Module config table. See |MiniInput.config|.

Usage ~

>lua

require('mini.input').setup() -- use default config

-- OR

require('mini.input').setup({}) -- replace {} with your config table

<

------------------------------------------------------------------------------

*MiniInput.config*

`MiniInput.config`

Defaults ~

>lua

MiniInput.config = {

-- Functions that control input lifecycle

handlers = {

-- Compute completion candidates

complete = nil,

-- Compute highlighting of current input

highlight = nil,

-- Handle input start, every key press, and input end

key = nil,

-- Show current input state

view = nil,

},

-- Default input scope: cursor/line/buffer/window/tabpage/editor/project

scope = 'editor',

}

<

# Handlers ~

*MiniInput.config.handlers*

`config.handlers` defines functions that are applied during |MiniInput-lifecycle|.

Every handler takes |MiniInput-state| as the first argument and is expected to

either modify it in place or return a new state table.

Use |MiniInput.apply_handler()| to apply a handler for a given |MiniInput-state|.

They can be set up as part of the config (will be used as default) or passed

directly as a part of |MiniInput.get()| call.

## Complete ~

`handlers.complete` is a handler intended to compute completion suggestions.

Takes |MiniInput-state| and `method` as arguments and is expected to modify

<complete> field. Default: |MiniInput.default_complete()|.

Only `complete.base` and `complete.items` are expected to be set by a complete

handler. Setting and modifying other fields (`complete.id` and `complete.method`)

is done in other handlers and as part of |MiniInput.apply_handler()|. Actually

showing completion information is up to the view handler.

This handler is usually applied manually inside a key handler via using

`MiniInput.apply_handler(state, 'complete', method)`. Like, for example,

in |MiniInput.default_key()| after <Tab> or <Up>.

Here is an example of a simple demo complete handler: >lua

local complete_handler = function(state, method)

if method == '' or method == 'xy' then

local text = vim.fn.strcharpart(state.input, 0, state.caret - 1)

local base = text:match('%S*$')

state.complete = { base = base, items = { base .. 'x', base .. 'y' } }

return

end

return MiniInput.default_complete(state, method)

end

require('mini.input').setup({ handlers = { complete = complete_handler } })

<

## Key ~

`handlers.key` is a handler intended to process every user key press.

Takes |MiniInput-state| and `key` as arguments. Argument `key` represents a key

that needs to be processed: a string if from the user input or `nil` if input

needs to be set up, refreshed, or torn down. Default: |MiniInput.default_key()|.

A string `key` can be two kinds:

- Forwarded from |getcharstr()| verbatim as a result of interactive key press.

Meaning it will be in escaped form and not as a |key-notation|: i.e. `"\r"`

and not `"<CR>"`. It also means that all kinds of combos (`<M-...>`, `<C-S-...>`),

mouse clicks, and wheel scrolls are also forwarded to key handler.

- Any string as part of `opts.init_keys` in |MiniInput.get()|. If a string

doesn't look like it came from |getcharstr()|, it is usually a good idea

to insert this string at caret as is.

The suggested overall approach for custom key handler is "if `key` is special -

act on it, if can be used in the input - insert at caret, ignore otherwise".

It is also important to never change the current mode (as in |vim-modes|)

for |MiniInput.get()| to work as expected.

Here is an example of a basic custom key handler: >lua

local custom_actions = {

[vim.keycode('<Left>')] = function(state)

state.caret = math.max(state.caret - 1, 1)

end,

[vim.keycode('<Right>')] = function(state)

local input_width = vim.fn.strchars(state.input)

state.caret = math.min(state.caret + 1, input_width + 1)

end,

[vim.keycode('<CR>')] = function(state) state.status = 'accept' end,

[vim.keycode('<Esc>')] = function(state) state.status = 'cancel' end,

}

local key_handler = function(state, key)

-- No need for special setup or teardown

if key == nil then return end

-- If key is special - act on it

if custom_actions[key] then return custom_actions[key](state) end

-- If key is not printable - do nothing

if vim.fn.match(key, '^[[:print:]]\\+$') < 0 then return end

-- Insert at caret

local caret, input = state.caret, state.input

local before_caret = vim.fn.strcharpart(input, 0, caret - 1)

local after_caret = vim.fn.strcharpart(input, caret - 1)

state.input = before_caret .. key .. after_caret

state.caret = caret + vim.fn.strchars(key)

-- No need to return anything as `state` is modified in place

end

require('mini.input').setup({ handlers = { key = key_handler } })

<

## Highlight ~

`handlers.highlight` is a handler intended to compute and set highlight info

about the current input. Takes |MiniInput-state| as the only argument and is

expected to modify <highlight> field. Default: |MiniInput.default_highlight()|.

See |MiniInput.gen_highlight| for built-in highlight handler generators.

It is usually a good idea to append to a <highlight> if it already exists.

This makes it work more robustly when combining highlights.

Here is a basic example that highlights all letters `a`: >lua

local hl_handler = function(state)

local highlight = {}

for col in string.gmatch(state.input, '()a') do

-- NOTE: range should use character (not byte) indexes

local char_col = vim.fn.charidx(state.input, col)

local range = { from = char_col, to = char_col, hl = 'Special' }

table.insert(highlight, range)

end

state.highlight = vim.list_extend(state.highlight or {}, highlight)

-- Possibly also apply default handler afterwards

return MiniInput.default_highlight(state)

end

require('mini.input').setup({ handlers = { highlight = hl_handler } })

<

## View ~

`handlers.view` is a handler intended to show the input state on screen.

Takes |MiniInput-state| as the only argument. Default: |MiniInput.default_view()|.

See |MiniInput.gen_view| for built-in view handler generators.

Example of view that uses |nvim_echo()| to show the input: >lua

local view_handler = function(state)

-- Process start and end of the input lifecycle

local is_start = state.status == 'start'

local is_end = state.status == 'accept' or state.status == 'cancel'

if is_start or is_end then vim.cmd('mode') end

if is_end then return end

-- Compute text-hl chunks that fit and show them

local chunks = MiniInput.state_to_chunks(state, vim.v.echospace)

vim.api.nvim_echo(chunks, false, {})

end

require('mini.input').setup({ handlers = { view = view_handler } })

<

# Scope ~

`config.scope` is a string that defines an input scope. It is meant as an extra

information for handlers to tweak their behavior (`view` style, etc.). Possible

values: `"cursor"`, `"line"`, `"buffer"`, `"window"`, `"tabpage"`, `"editor"`, `"project"`.

------------------------------------------------------------------------------

*MiniInput.get()*

`MiniInput.get`({opts})

Get input from the user

# Lifecycle ~

*MiniInput-lifecycle*

This module implements custom lifecycle to interact with the user. It starts

when calling |MiniInput.get()| and ends when a value is returned.

Only one active input is allowed simultaneously.

The basic cycle unit is a step that processes a `key` (string or `nil`). It is

done by calling relevant handlers in order: key handler with `key` as a second

argument, highlight handler, view handler. |MiniInput.apply_handler()| is used

to apply each handler and the output of one is used as the input for the next.

During a step some state fields are automatically removed:

- <highlight> is removed before applying a key handler to always have the most

up to date highlighting.

- <complete> is removed if it was not changed after applying a key handler but

something else in the state besides <highlight> did change. This is meant as

an automatic stop of completion when it is not advancing.

If a step sets an ending state <status> (i.e. `"accept"` or `"cancel"`), the input

is finished by extra finishing step (see below).

The order of operations is as follows:

- Create initial |MiniInput-state| based on the input `opts`, with defaults

inferred from |MiniInput.config|, and `vim.b.miniinput_config`.

- Set <status> to `"start"`.

- Advance one step with `key=nil`. This is meant as a "setup" step for handlers.

- Set <status> to `"progress"`.

- Process `opts.init_keys` one item per step with `key` set to the string item.

- Wait for user to press a key (via |getcharstr()|). The key string (in escaped

form and not as a |key-notation|; i.e. `"\r"` and not `"<CR>"`) is then used

to advance a step. Note: <C-c> is hard coded to cancel the input.

- Repeat previous step until the ending <status> (`"accept"` or `"cancel"`).

- Finish the input:

- Perform a "teardown" step with `key=nil`.

- If <errmsg> is set, throw an |error()|.

- If input is accepted (even if empty) and not hidden, add <input> to

the history. Get the whole history with |MiniInput.get_history()|.

- Return <input> if <status> is `"accept"`, `nil` otherwise.

Parameters ~

{opts} `(table|nil)` Options. Possible fields:

- <completion> `(string)` - completion method. Default: `''` to use default

completion method of the `complete` handler.

- <handlers> `(table)` - same as in |MiniInput.config.handlers|, used only for

the duration of the current input.

- <hide> `(boolean)` - whether input should be hidden. Default: `false`.

Note: this does not guarantee a total security of the input, only that

the typed characters are expected to not be shown on screen and not added

to the history. If set:

- The `view` handler is expected to not directly show current input.

Like replace characters with pre-defined string or fully not show.

- The `complete` and `highlight` handlers are not called.

- Accepted input will not be added to the history.

- <init_keys> `(table)` - array of string keys that are emulated before asking

for the user input. Using values that can be an output of |getcharstr()|

should be preferred, but a key handler should work with any string.

Default: `{}`.

- <prompt> `(string)` - intention of the input, same as in |input()|.

Default: `"Input"`.

- <scope> `(string)` - same as in |MiniInput.config|. Default: the value from

`MiniInput.config` with some hard coded exceptions (on Neovim<0.12.3):

- |vim.lsp.buf.rename()| will use `"cursor"` if no `new_name` is supplied.

Return ~

`(string|nil)` User input (from the <input> state field) if accepted, even if

empty. `nil` if canceled or there was an active input.

Usage ~

>lua

local input = MiniInput.get({

-- Intention of the input

prompt = 'New value',

-- The input is for something at cursor

scope = 'cursor',

-- Emulate pressing `a`, `<BS>`, and `b`

init_keys = { 'a', vim.keycode('<BS>'), 'b' },

})

<

------------------------------------------------------------------------------

*MiniInput.ui_input()*

`MiniInput.ui_input`({opts}, {on_confirm})

A |vim.ui.input()| implementation

Function which can be used to directly override |vim.ui.input()| to use this

module functionality. Set automatically in |MiniInput.setup()|.

Usage ~

To preserve original `vim.ui.input()`: >lua

local ui_input_orig = vim.ui.input

require('mini.input').setup()

vim.ui.input = ui_input_orig

<

------------------------------------------------------------------------------

*MiniInput.get_state()*

`MiniInput.get_state`()

Get current input state

Return ~

`(table|nil)` Current |MiniInput-state| if input is active, `nil` otherwise. Notes:

- For hidden input (`state.opts.hide=true`), both <caret> and <input> are `nil`

to actually hide the input.

------------------------------------------------------------------------------

*MiniInput.get_history()*

`MiniInput.get_history`()

Get input history

Return ~

`(table)` Array with data about all previous non-hidden inputs (from earliest

to latest). Each element is a table with the following fields:

- <cwd> `(string)` - |current-directory| at the time of input's end.

- <input> `(string)` - input result.

- <prompt> `(string)` - `opts.prompt` supplied in |MiniInput.get()|.

- <scope> `(string)` - `opts.scope` supplied in |MiniInput.get()|.

------------------------------------------------------------------------------

*MiniInput.set_history()*

`MiniInput.set_history`({history})

Set input history

Parameters ~

{history} `(table)` Array describing all previous inputs. Same structure

as |MiniInput.get_history()| output.

------------------------------------------------------------------------------

*MiniInput.refresh()*

`MiniInput.refresh`()

Refresh active input

Performs one step of |MiniInput-lifecycle| with `key=nil`.

------------------------------------------------------------------------------

*MiniInput.gen_highlight*

`MiniInput.gen_highlight`

Highlight generators

This is a table with function elements. Call to actually get a view function.

------------------------------------------------------------------------------

*MiniInput.gen_highlight.treesitter()*

`MiniInput.gen_highlight.treesitter`({lang})

Highlight with tree-sitter

Parameters ~

{lang} `(string)` A language of tree-sitter parser to use.

Return ~

`(function)` A highlight handler. Seem |MiniInput.config.handlers|.

------------------------------------------------------------------------------

*MiniInput.gen_view*

`MiniInput.gen_view`

View generators

This is a table with function elements. Call to actually get a view function.

Each element accepts <style> option which fine tunes the input view.

With default key handler (|MiniInput.default_key()|) it can be adjusted

interactively by pressing <C-s>.

Each element also accepts <to_chunks> option. It is a function that takes

a |MiniInput-state| and `max_width` arguments and returns an array of `{ text, hl }`

chunks that fit into `max_width` display width (as in |strdisplaywidth()|).

This is a way to adjust how input is shown. Like caret/hide symbols, etc.

By default uses |MiniInput.state_to_chunks()|, which also means:

- All control characters (like literal `\t`, `\n`, etc.) will be translated

via |keytrans()|.

Example: >lua

local input = require('mini.input')

-- Adjust how state is converted to text-hl chunks

local to_chunks_opts = {

symbol_caret = '_',

symbol_hide = '*',

-- Do not include prompt and hint in `floatwin` handler

include_prompt = false,

include_hint = false,

}

local to_chunks = function(state, max_width)

return MiniInput.state_to_chunks(state, max_width, to_chunks_opts)

end

-- Supply custom `to_chunks` as an option

local view_opts = { to_chunks = to_chunks }

input.setup({ handlers = { view = input.gen_view.floatwin(view_opts) } })

<

------------------------------------------------------------------------------

*MiniInput.gen_view.floatwin()*

`MiniInput.gen_view.floatwin`({opts})

Floating window view

Show input inside a floating window. Prompt and completion hints are shown

in title and footer.

Window position and dimensions are computed based on state's <scope> and

`opts.style`:

- `scope="cursor"` is shown near the cursor. For example, `style="BL"` will

have bottom left corner at nearest top right cell relative to the cursor.

- `scope="line"` is shown near the current line. For example, `style="BL"` will

have bottom left corner at left side above the line.

- `scope="buffer"` and `scope="window"` will be shown relative to the current

window. For example, `style="BL"` will be shown in the bottom left corner.

- `scope="tabpage"`, `scope="editor"`, `scope="project"` will be shown relative to

the overall Neovim instance. For example, `style="BL"` will be shown in the

bottom left corner.

Identifiers of floating window and its buffer are stored as `floatwin_win_id`

and `floatwin_buf_id` in |MiniInput-state| <data> field. Floating window is

not focused and cursor position is not the same as caret position.

Parameters ~

{opts} `(table|nil)` Options. Possible fields:

- <adjust_config> `(function)` - function to adjust default config. Will be

called with two arguments: current |MiniInput-state| and a window config

(always with `relative="editor"` and `anchor="NW"`) computed based

on `opts.style`. Should return an adjusted window config.

Default: `function(state, config) return config end`.

- <style> `(string)` - a two character description of how to show the window.

Default: `"BL"`.

First character describes vertical position:

- `"T"` - top window border will be at scope's reference top border.

- `"M"` - middle between top and bottom window borders will be at the

middle of scope's reference top and bottom borders.

- `"B"` - bottom window border will be at scope's reference bottom border.

Second character describes horizontal position:

- `"L"` - left window border will be at scope's reference left border.

- `"M"` - middle between left and right window borders will be at the

middle of scope's reference left and right borders.

- `"R"` - right window border will be at scope's reference right border.

- <to_chunks> `(function)` - a function that takes |MiniInput-state| and

`max_width` arguments and returns an array of `{ text, hl }` chunks that fit

into `max_width` display width. See |MiniInput.state_to_chunks()|.

Usage ~

>lua

local input = require('mini.input')

-- Use border different from 'winborder'

local adjust_config = function(_, config)

config.border = 'double'

return config

end

-- Choose initial style based on the scope

local floatwin = input.gen_view.floatwin

local view_tm = floatwin({ style = 'TM', adjust_config = adjust_config })

local view_bl = floatwin({ style = 'BL', adjust_config = adjust_config })

local view_handler = function(state)

local scope, view = state.opts.scope, view_tm

if scope == 'cursor' or scope == 'line' then view = view_bl end

return view(state)

end

input.setup({ handlers = { view = view_handler } })

<

------------------------------------------------------------------------------

*MiniInput.gen_view.uiline()*

`MiniInput.gen_view.uiline`({opts})

UI line (statusline, tabline, winbar) view

Parameters ~

{opts} `(table|nil)` Options. Possible fields:

- <style> `(string)` - which UI line to use. One of `"statusline"`,

`"tabline"`, `"winbar"`. Default: `"statusline"`.

- <to_chunks> `(function)` - a function that takes |MiniInput-state| and

`max_width` arguments and returns an array of `{ text, hl }` chunks that fit

into `max_width` display width. See |MiniInput.state_to_chunks()|.

Usage ~

>lua

local input = require('mini.input')

-- Choose initial style based on the scope

local view_tabline = input.gen_view.uiline({ style = 'tabline' })

local view_winbar = input.gen_view.uiline({ style = 'winbar' })

local view_handler = function(state)

local scope, view = state.opts.scope, view_winbar

if scope == 'tabpage' or scope == 'editor' or scope == 'project' then

view = view_tabline

end

return view(state)

end

input.setup({ handlers = { view = view_handler } })

<

------------------------------------------------------------------------------

*MiniInput.gen_view.virtual()*

`MiniInput.gen_view.virtual`({opts})

Virtual (line, text) view

Parameters ~

{opts} `(table|nil)` Options. Possible fields:

- <style> `(string)` - how to display virtual text. One of `"above"`, `"below"`,

`"inline"`. Default: `"above"`.

- <to_chunks> `(function)` - a function that takes |MiniInput-state| and

`max_width` arguments and returns an array of `{ text, hl }` chunks that fit

into `max_width` display width. See |MiniInput.state_to_chunks()|.

Usage ~

>lua

-- Choose different initial style

local input = require('mini.input')

local view_handler = input.gen_view.virtual({ style = 'inline' })

input.setup({ handlers = { view = view_handler } })

<

------------------------------------------------------------------------------

*MiniInput.default_key()*

`MiniInput.default_key`({state}, {key}, {opts})

Default key handler

Emulates most of |Command-line-mode| editing (|cmdline-editing|):

- Accept: <CR>. To insert literal newline, type `<C-j>`.

- Cancel: <Esc> or <C-c>.

- Move caret:

- <Left>, <Right> - one character to left / right.

- <M-h>, <M-l> - one character to left / right.

- <S-Left>, <S-Right> - one word to left / right.

- <C-b>, <C-e> (if no completion) - to start / end of input.

- <Home>, <End> - to start / end of input.

- Delete:

- <BS> / <C-h> - to caret's left. If `opts.autopair` is enabled, also delete

a character to caret's right if it formed a respected character pair.

See "Autopair".

- <Del> - at caret.

- <C-u> - from start to caret. As |c_CTRL-U|.

- <C-w> - contiguous keyword or non-keyword to caret's left. As |c_CTRL-W|.

- Insert at caret:

- <C-k> - digraph based on the next two pressed keys. As |c_CTRL-K|.

- <C-r> - content of a register. As |c_CTRL-R| including support for

special <C-a>, <C-f>, <C-l>, <C-w> keys for a register.

- <C-v>, <C-q> - next key literally. As |c_CTRL-V| and |i_CTRL-V_digit|

(all digits must be typed in full or stopped with <C-c>).

- Pasting from system |clipboard| is supported for "non-streaming" paste (as

described in |vim.paste()|).

- Autopair (if `opts.autopair` is set) is similar to |mini.pairs|:

- Opening characters `(`, `[`, `{` always insert a `()`, `[]`, `{}` pair and places

caret inside of it.

- Closing characters `)`, `]`, `}` move caret to the right if there is the same

character to the right.

- Closeopen characters single+double quotes and backtick perform "close"

action if possible and "open" action if not.

- In all cases press <C-v> before special character to insert it verbatim.

- Completion:

- <Tab>, <S-Tab> - start with `state.opts.completion` method if not active

and advance through active completion (i.e. replace currently displayed

at caret item with the next one).

Note: type `<C-v><Tab>` to insert literal `\t`.

- <C-n>, <C-p>, <Up>, <Down> - start with `"history"` method if not active

and advance through active completion.

- <C-e> - cancel and return to initial input and caret.

- <C-y> - accept current candidate. Note: it will also be accepted after

any key that doesn't advance completion.

- Miscellaneous:

- <C-o> - change scope of the input. Cycles through all available ones.

- <C-s> - change view style. Works only with |MiniInput.gen_view| view

handlers. Cycles through all available ones.

- <C-x> - toggle hide/unhide of the input.

- Special keys (combo, mouse, but not whitespace) not listed above - ignored.

Anything else (even more than a single character) - inserted at caret.

Parameters ~

{state} `(table)` Current |MiniInput-state|.

{key} `(string|nil)` A key to process. Should be escaped (`"\r"`, not `"<CR>"`).

See |vim.keycode()|.

{opts} `(table|nil)` Options. Possible fields:

- <autopair> `(boolean)` - whether perform add autopair. Default: `false`.

------------------------------------------------------------------------------

*MiniInput.default_highlight()*

`MiniInput.default_highlight`({state})

Default highlight handler

During active completion highlights added (computed via |matchfuzzy()|)

characters with `MiniInputAdded` group.

Parameters ~

{state} `(table)` Current |MiniInput-state|.

------------------------------------------------------------------------------

*MiniInput.default_view()*

`MiniInput.default_view`({state})

Default view handler

Same as |MiniInput.gen_view.floatwin()| with default options.

Parameters ~

{state} `(table)` Current |MiniInput-state|.

------------------------------------------------------------------------------

*MiniInput.default_complete()*

`MiniInput.default_complete`({state}, {method}, {opts})

Default complete handler

Supported methods:

- `""` (default) - complete with buffer keywords (|'iskeyword'|) that match

a keyword at caret's left.

- `"history"` - complete with |MiniInput.get_history()| inputs that have current

input to caret's left as a prefix. If `opts.precise_history`, only use history

entries that have all info fields same as the current state. Orders from

earliest to latest. To initiate with the latest history match, press

<Up> or <C-p> with default key handler.

- `"cmdline"` - treat input as |Command-line| text and show completions at caret.

Note: as there is no |getcmdcomplpat()| variant to use outside of Command-line

mode, the base is inferred from |getcompletion()| output as the widest text to

caret's left that matches all candidates: fuzzily if |'wildoptions'| contains

`fuzzy`, as a prefix otherwise (respecting |'ignorecase'| and |'smartcase'|).

If none - use empty string. There are limitations, but this is good enough.

- Every method supported by |getcompletion()|. Base is computed as the keyword

at caret's left.

Parameters ~

{state} `(table)` Current |MiniInput-state|.

{method} `(string)` Completion method.

{opts} `(table|nil)` Options. Possible fields:

- <precise_history> `(boolean)` - whether for `method='history'` try to match

only entries that have <cwd> as |current-directory|, same <scope> and

<prompt> as in current state. Default: `true`.

Usage ~

>lua

-- Do not match history precisely

local complete_opts = { precise_history = false }

local complete_handler = function(state, method)

return MiniInput.default_complete(state, method, complete_opts)

end

require('mini.input').setup({ handlers = { complete = complete_handler } })

<

------------------------------------------------------------------------------

*MiniInput.state_to_chunks()*

`MiniInput.state_to_chunks`({state}, {max_width}, {opts})

Convert state into text-hl chunks

- Treat `state.highlight` elements in increasing priority, i.e. later ones

are placed "on top" of the previous ones if they overlap.

- Uses |MiniInput-hl-groups|.

- Multiline input (i.e. with newline characters `\n`) is shown as a single line.

- Treats `max_width` as display width (|strdisplaywidth()|).

- Truncates output chunks trying to center the caret.

Parameters ~

{state} `(table)` A |MiniInput-state|.

{max_width} `(number|nil)` Maximum allowed display width. Can be |math.huge|.

{opts} `(table|nil)` Options. Possible fields:

- <keytrans> `(boolean)` - whether to translate control characters (escaped

version of `<C-...>`). Default: `true`.

- <include_prompt> `(boolean)` - whether to start chunks with state prompt.

Default: `true`.

- <include_hint> `(boolean)` - whether to show complete hint to caret's right.

Default: `true`.

- <symbol_caret> `(string)` - string to use for caret. Default: `"▏"`.

- <symbol_hide> `(string)` - string to use for each input character when

input is hidden. Default: `"•"`.

Return ~

`(table)` An array of text-hl chunks that fit `max_width` display width.

------------------------------------------------------------------------------

*MiniInput.apply_handler()*

`MiniInput.apply_handler`({state}, {name}, {arg})

Apply state's handler

Given |MiniInput-state|, apply its handler (from `state.opts.handlers`) and

return the modified state.

Notes:

- Nothing is done for highlight and complete handlers when input is hidden.

- Applying complete handler ensures that <complete> state field has <id> set

to 0 (as it assumes new completion) and <method> to the input argument

(empty string if there was no argument).

- Error during handler application is stored as <errmsg> field of output state

if there is an active input. It is propagated via |error()| otherwise.

- Handler output is validated to be a valid |MiniInput-state|. If not - return

input `state`. Note: it still could be changed if handler modified in place.

Parameters ~

{state} `(table)` A |MiniInput-state|.

{name} `(string)` Valid handler name.

{arg} `(any)` Extra handler argument: like `key` for key handler and `method`

for complete handler.

Return ~

`(table)` A |MiniInput-state| as a result of applied handler. If handler returned

nothing, the input `state` is returned (assumes it was modified in place).

vim:tw=78:ts=8:noet:ft=help:norl: