wsdjeg/picker.nvim

highly customizable and extensible Neovim fuzzy finder

picker.nvim

picker.nvim is a highly customizable and extensible Neovim fuzzy finder plugin written in lua.

• Features
• Installation
• Usage
  • Picker Command
  • Key bindings
• Builtin sources
  • files
  • cmd_history
  • picker_config
  • highlights
  • async_files
  • colorscheme
  • buftags
  • buffers
  • lines
  • help_tags
  • qflist
  • loclist
  • registers
  • jumps
  • marks
  • lsp_document_symbols
  • lsp_workspace_symbols
  • lsp_references
  • emoji
  • key-mappings
• Third party sources
• Custom source
• Custom layout
• FAQ
• Self-Promotion
• Feedback
• Credits

Features

• 18 built-in extensions and some third-party extensions
• simple, fast fuzzy match engine powered by fzy.
• simple API for creating custom source
• support custom layout.

Installation

• use nvim-plug

require("plug").add({
	{
		"wsdjeg/picker.nvim",
		config = function()
			require("picker").setup({
				filter = {
					ignorecase = false, -- ignorecase (boolean): defaults to false
				},
				window = {
					width = 0.8, -- set picker screen width, default is 0.8 * vim.o.columns
					height = 0.8,
					col = 0.1,
					row = 0.1,
					current_icon = ">",
					current_icon_hl = "CursorLine",
					enable_preview = false,
					preview_timeout = 500,
					show_score = false,  -- display/hide match score at the end of each item.
				},
				highlight = {
					matched = "Tag",
					score = "Comment",
				},
				prompt = {
					position = "bottom", -- set prompt position, bottom or top
					icon = ">",
					icon_hl = "Error",
					insert_timeout = 100,
					title = true, -- display/hide source name
				},
				mappings = {
					close = "<Esc>",
					next_item = "<Tab>",
					previous_item = "<S-Tab>",
					open_item = "<Enter>",
					toggle_preview = "<C-p>",
				},
			})
		end,
	},
})

Usage

Picker Command

1. fuzzy finder picker source.

run :Picker command without source name.

:Picker

2. open picker source.

run :Picker command with a name of source.

:Picker <name>

3. specific default input

with --input option, users also can specific default input text.

:Picker file --input=foo

or use <cword> for word under cursor.

:Picker help_tags --input=<cword>

Key bindings

In picker prompt window, the these mappings are defined by default.

key binding	description
Tab	next item
S-Tab	previous item
Enter	default action
Esc	close picker

Builtin sources

source	description
buffers	listed buffers
buftags	ctags outline for current buffer
cmd_history	results from :history :
colorscheme	all colorschemes
files	files in current dir
help_tags	neovim help tags source
highlights	highlight group source
jumps	jump list
lines	lines in current buffer
loclist	location list source
lsp_document_symbols	document symbols result from lsp client
lsp_references	lsp references
lsp_workspace_symbols	workspace symbols
marks	marks list
picker_config	picker config source
qflist	quickfix source
registers	registers context
emoji	emoji entries
key-mappings	key mappings

files

The default commands for listing files is {'rg', '--files'}. this can be changed via:

require("picker.sources.files").set({ cmd = { "rg", "--files" } })

key binding	description
<Enter>	open select file
<C-v>	open select file in vertical split
<C-t>	open select file in new tabpage

cmd_history

filter results from :history cmd.

key binding	description
<Enter>	execute select command
<C-d>	delete select command history

picker_config

filter and setup picker.nvim without changing configuration file.

items	description
prompt-top	change the prompt position to top
prompt-bottom	change the prompt position to bottom
show-score	display matched score
hide-score	hide matched score
ignrecase	change filter ignrecase to true
noignrecase	change filter ignrecase to false

key binding	description
<Enter>	set selected picker config

highlights

filter results from :highlight

key binding	description
<Enter>	yank selected highlight group name

async_files

same as files source, but require job.nvim.

key binding	description
<Enter>	open select file

colorscheme

filter colorschemes.

key binding	description
<Enter>	change to selected colorscheme

buftags

filter ctags outline, require ctags command.

key binding	description
<Enter>	jump to select tag

buffers

file results from nvim_list_bufs()

key binding	description
<Enter>	switch to select buffer

lines

key binding	description
<Enter>	jump to selected line

help_tags

key binding	description
<Enter>	jump selected help tag

qflist

key binding	description
<Enter>	jump selected quickfix list item

loclist

key binding	description
<Enter>	jump selected loclist item

registers

key binding	description
<Enter>	paste selected context

jumps

key binding	description
<Enter>	jump selected position

marks

key binding	description
<Enter>	jump selected position

lsp_document_symbols

key binding	description
<Enter>	jump selected symbol

lsp_workspace_symbols

key binding	description
<Enter>	jump selected symbol

lsp_references

key binding	description
<Enter>	jump selected reference

emoji

filter emoji entries from muan/unicode-emoji-json.

This source will try to use job.nvim to download emoji json data, if job.nvim is not installed, vim.fn.system() will be used.

key binding	description
<Enter>	insert selected emoji

key-mappings

key binding	description
<Enter>	trigger selected key mapping

Third party sources

source	description
mru	most recent used files, need mru.nvim
project	project history, need rooter.nvim
bookmarks	all bookmarks, need bookmarks.nvim
zettelkasten	zettelkasten notes source from zettelkasten.nvim
zettelkasten_tags	zettelkasten tags source from zettelkasten.nvim
git-branch	git branch source from git.nvim
music-player	music-player source form music-player.nvim
plug	plugins source for nvim-plug
async_files	async files source, require job.nvim

Custom source

a source main module should be picker.sources.<name>, that means you can create a custom source in lua/picker/sources/ directory in your plugin.

--- @class PickerSource
--- @field get function
--- @field default_action function
--- @field __results nil | table<string>
--- @field preview_win boolean
--- @field preview function
--- @field set function
--- @field actions? table

Custom layout

picker.nvim use default layout by default. a layout should provide following public functions:

local M = {}

---@class PickerLayout
---@field prompt_buf integer
---@field prompt_win integer
---@field list_buf integer
---@field list_win integer
---@field preview_buf integer
---@field preview_win integer

---@param source PickerSource
---@param config PickerConfig
---@return PickerLayout
function M.render_windows(source, config)
end

return M

FAQ

1. how to disable nvim-cmp in picker.nvim buffer?

require("cmp").setup({
	enabled = function()
		if vim.bo.filetype == "picker-prompt" then
			return false
		end
		return true
	end,
})

2. how to use picker.nvim as vim.ui.select?

vim.ui.select = function(items, opt, callback)
	local source = {}
	opt = opt or {}
	if opt.prompt then
		source.name = opt.prompt
	else
		source.name = "Select one of:"
	end

	source.get = function()
		local entrys = {}
		for idx, item in ipairs(items) do
			local entry = {
				value = item,
				idx = idx, -- this also can be nil
			}

			if opt.format_item then
				entry.str = opt.format_item(item)
			else
				entry.str = item
			end
			table.insert(entrys, entry)
		end
		return entrys
	end

	source.default_action = function(entry)
		if callback then
			callback(entry.value, entry.idx)
		end
	end

	require("picker.windows").open(source, {
		buf = vim.api.nvim_get_current_buf(),
	})
end

Self-Promotion

Like this plugin? Star the repository on GitHub.

Love this plugin? Follow me on GitHub.

Feedback

If you encounter any bugs or have suggestions, please file an issue in the issue tracker

Credits

• telescope.nvim
• denite.nvim