stevearc/dressing.nvim

github github
utility
star 281
stars
alert-circle 0
open issues
users 3
subscribers
git-branch 4
forks
CREATED

2021-12-02

UPDATED

6 days ago


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

Neovim 0.5+

On versions prior to 0.6, this plugin will act as a polyfill for vim.ui

Screenshots

vim.input replacement (handling a LSP rename)

Screenshot from 2021-12-09 17-36-16

vim.select (telescope)

Screenshot from 2021-12-02 19-46-01

vim.select (fzf)

Screenshot from 2021-12-02 19-46-54

vim.select (nui)

Screenshot from 2021-12-02 19-47-56

vim.select (built-in)

Screenshot from 2021-12-04 17-14-32

Installation

dressing.nvim supports all the usual plugin managers

require('packer').startup(function()
    use {'stevearc/dressing.nvim'}
end)
require "paq" {
    {'stevearc/dressing.nvim'};
}
Plug 'stevearc/dressing.nvim'
call dein#add('stevearc/dressing.nvim')
git clone --depth=1 https://github.com/stevearc/dressing.nvim.git ~/.vim/bundle/
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 = "➤ ",

    -- When true, <Esc> will close the modal
    insert_only = true,

    -- These are passed to nvim_open_win
    anchor = "SW",
    relative = "cursor",
    row = 0,
    col = 0,
    border = "rounded",

    -- These can be integers or a float between 0 and 1 (e.g. 0.4 for 40%)
    prefer_width = 40,
    max_width = nil,
    min_width = 20,

    -- Window transparency (0-100)
    winblend = 10,
    -- Change default highlight groups (see :help winhl)
    winhighlight = "",

    -- 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" },

    -- Options for telescope selector
    telescope = {
      -- can be 'dropdown', 'cursor', or 'ivy'
      theme = "dropdown",
    },

    -- 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",
      },
      max_width = 80,
      max_height = 40,
    },

    -- Options for built-in selector
    builtin = {
      -- These are passed to nvim_open_win
      anchor = "NW",
      relative = "cursor",
      row = 0,
      col = 0,
      border = "rounded",

      -- 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%)
      width = nil,
      max_width = 0.8,
      min_width = 40,
      height = nil,
      max_height = 0.9,
      min_height = 10,
    },

    -- Used to override format_item. See :help dressing-format
    format_item_override = {},

    -- see :help dressing_get_config
    get_config = nil,
  },
})

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
  }
})
  • 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 and vim.ui.input implementations
  • nvim-notify - doing pretty much the same thing but for vim.notify
  • nui.nvim - provides common UI components for plugin authors