12b808a686
fix issue when operating from a floating window |
||
---|---|---|
.github | ||
autoload | ||
doc | ||
lua/dressing | ||
plugin | ||
tests | ||
.gitignore | ||
.luacheckrc | ||
.stylua.toml | ||
LICENSE | ||
README.md | ||
run_tests.sh |
README.md
Dressing.nvim
With the release of Neovim 0.6 we were given the start of extensible core UI hooks (vim.ui.select and vim.ui.input). They exist to allow plugin authors to override them with improvements upon the default behavior, so that's exactly what we're going to do.
It is a goal to match and not extend the core Neovim API. All options that core respects will be respected, and we will not accept any custom parameters or options in the functions. Customization will be done entirely using a separate configuration method.
- Requirements
- Screenshots
- Installation
- Configuration
- Highlights
- Advanced configuration
- Notes for plugin authors
- Alternative and related projects
Requirements
Neovim 0.7.0+ (for earlier versions, use the nvim-0.5 branch)
Screenshots
vim.input
replacement (handling a LSP rename)
vim.select
(telescope)
vim.select
(fzf)
vim.select
(nui)
vim.select
(built-in)
Installation
dressing.nvim supports all the usual plugin managers
Packer
require('packer').startup(function()
use {'stevearc/dressing.nvim'}
end)
Paq
require "paq" {
{'stevearc/dressing.nvim'};
}
vim-plug
Plug 'stevearc/dressing.nvim'
dein
call dein#add('stevearc/dressing.nvim')
Pathogen
git clone --depth=1 https://github.com/stevearc/dressing.nvim.git ~/.vim/bundle/
Neovim native package
git clone --depth=1 https://github.com/stevearc/dressing.nvim.git \
"${XDG_DATA_HOME:-$HOME/.local/share}"/nvim/site/pack/dressing.nvim/start/dressing.nvim
Configuration
If you're fine with the defaults, you're good to go after installation. If you want to tweak, call this function:
require('dressing').setup({
input = {
-- Set to false to disable the vim.ui.input implementation
enabled = true,
-- Default prompt string
default_prompt = "Input:",
-- Can be 'left', 'right', or 'center'
prompt_align = "left",
-- When true, <Esc> will close the modal
insert_only = true,
-- When true, input will start in insert mode.
start_in_insert = true,
-- These are passed to nvim_open_win
anchor = "SW",
border = "rounded",
-- 'editor' and 'win' will default to being centered
relative = "cursor",
-- These can be integers or a float between 0 and 1 (e.g. 0.4 for 40%)
prefer_width = 40,
width = nil,
-- min_width and max_width can be a list of mixed types.
-- min_width = {20, 0.2} means "the greater of 20 columns or 20% of total"
max_width = { 140, 0.9 },
min_width = { 20, 0.2 },
-- Window transparency (0-100)
winblend = 10,
-- Change default highlight groups (see :help winhl)
winhighlight = "",
-- Set to `false` to disable
mappings = {
n = {
["<Esc>"] = "Close",
["<CR>"] = "Confirm",
},
i = {
["<C-c>"] = "Close",
["<CR>"] = "Confirm",
["<Up>"] = "HistoryPrev",
["<Down>"] = "HistoryNext",
},
},
override = function(conf)
-- This is the config that will be passed to nvim_open_win.
-- Change values here to customize the layout
return conf
end,
-- see :help dressing_get_config
get_config = nil,
},
select = {
-- Set to false to disable the vim.ui.select implementation
enabled = true,
-- Priority list of preferred vim.select implementations
backend = { "telescope", "fzf_lua", "fzf", "builtin", "nui" },
-- Trim trailing `:` from prompt
trim_prompt = true,
-- Options for telescope selector
-- These are passed into the telescope picker directly. Can be used like:
-- telescope = require('telescope.themes').get_ivy({...})
telescope = nil,
-- Options for fzf selector
fzf = {
window = {
width = 0.5,
height = 0.4,
},
},
-- Options for fzf_lua selector
fzf_lua = {
winopts = {
width = 0.5,
height = 0.4,
},
},
-- Options for nui Menu
nui = {
position = "50%",
size = nil,
relative = "editor",
border = {
style = "rounded",
},
buf_options = {
swapfile = false,
filetype = "DressingSelect",
},
win_options = {
winblend = 10,
},
max_width = 80,
max_height = 40,
min_width = 40,
min_height = 10,
},
-- Options for built-in selector
builtin = {
-- These are passed to nvim_open_win
anchor = "NW",
border = "rounded",
-- 'editor' and 'win' will default to being centered
relative = "editor",
-- Window transparency (0-100)
winblend = 10,
-- Change default highlight groups (see :help winhl)
winhighlight = "",
-- These can be integers or a float between 0 and 1 (e.g. 0.4 for 40%)
-- the min_ and max_ options can be a list of mixed types.
-- max_width = {140, 0.8} means "the lesser of 140 columns or 80% of total"
width = nil,
max_width = { 140, 0.8 },
min_width = { 40, 0.2 },
height = nil,
max_height = 0.9,
min_height = { 10, 0.2 },
-- Set to `false` to disable
mappings = {
["<Esc>"] = "Close",
["<C-c>"] = "Close",
["<CR>"] = "Confirm",
},
override = function(conf)
-- This is the config that will be passed to nvim_open_win.
-- Change values here to customize the layout
return conf
end,
},
-- Used to override format_item. See :help dressing-format
format_item_override = {},
-- see :help dressing_get_config
get_config = nil,
},
})
Highlights
The built-in vim.ui.input
and vim.ui.select
components mostly use the
standard highlight groups for neovim floating windows (e.g. NormalFloat
for
the text, FloatBorder
for the border). In addition, the window title uses a
non-standard FloatTitle
group that is linked to FloatBorder
by default.
A common way to adjust the highlighting of just the dressing windows is by
providing a winhighlight
option in the config. For example, winhighlight = 'NormalFloat:DiagnosticError'
would change the default text color in the dressing windows. See :help winhighlight
for more details.
Note that you can't change FloatTitle
via winhighlight
since it is not a
built-in group.
Advanced configuration
For each of the input
and select
configs, there is an option
get_config
. This can be a function that accepts the opts
parameter that
is passed in to vim.select
or vim.input
. It must return either nil
(to
no-op) or config values to use in place of the global config values for that
module.
For example, if you want to use a specific configuration for code actions:
require('dressing').setup({
select = {
get_config = function(opts)
if opts.kind == 'codeaction' then
return {
backend = 'nui',
nui = {
relative = 'cursor',
max_width = 40,
}
}
end
end
}
})
Notes for plugin authors
TL;DR: you can customize the telescope vim.ui.select
implementation by passing telescope
into opts
.
The vim.ui
hooks are a great boon for us because we can now assume that users
will have a reasonable UI available for simple input operations. We no longer
have to build separate implementations for each of fzf, telescope, ctrlp, etc.
The tradeoff is that vim.ui.select
is less customizable than any of these
options, so if you wanted to have a preview window (like telescope supports), it
is no longer an option.
My solution to this is extending the opts
that are passed to vim.ui.select
.
You can add a telescope
field that will be passed directly into the picker,
allowing you to customize any part of the UI. If a user has both dressing and
telescope installed, they will get your custom picker UI. If either of those
are not true, the selection UI will gracefully degrade to whatever the user has
configured for vim.ui.select
.
An example of usage:
vim.ui.select({'apple', 'banana', 'mango'}, {
prompt = "Title",
telescope = require("telescope.themes").get_cursor(),
}, function(selected) end)
For now this is available only for the telescope backend, but feel free to request additions.
Alternative and related projects
- telescope-ui-select - provides a
vim.ui.select
implementation for telescope - nvim-fzy - fzf alternative that also provides a
vim.ui.select
implementation (#13) - guihua.lua - multipurpose GUI library that provides
vim.ui.select
andvim.ui.input
implementations - nvim-notify - doing pretty much the
same thing but for
vim.notify
- nui.nvim - provides common UI components for plugin authors