pickme.nvim

One Picker to rule them all 💍👑

pickme.nvim in action

A unified interface for multiple Neovim picker plugins (Telescope, FZF-Lua, and Snacks). Write your code once and let users choose their preferred picker backend!

• Auto-detects available picker providers based on your configuration
• Seamlessly switch between Telescope, FZF-Lua, and Snacks.picker
• 40+ common pickers that work across all providers
• Nice collection of exclusive pickers for each provider
• Custom picker API for creating your own powerful pickers
• Sensible default keybindings

Using lazy.nvim:

{
  '2KAbhishek/pickme.nvim',
  cmd = 'PickMe',
  event = 'VeryLazy',
  dependencies = {
    -- Include at least one of these pickers:
    'folke/snacks.nvim', -- For snacks.picker
    -- 'nvim-telescope/telescope.nvim', -- For telescope
    -- 'ibhagwan/fzf-lua', -- For fzf-lua
  },
  opts = {
    picker_provider = 'snacks', -- Default provider
  },
}

require('pickme').setup({
  -- Choose your preferred picker provider
  picker_provider = 'snacks', -- Options: 'snacks' (default), 'telescope', 'fzf_lua'

  -- Auto-detect available picker providers (default: true)
  -- If the specified picker_provider is not available, will try to use one from provider_priority list
  detect_provider = true,

  -- Add default keybindings (default: true)
  -- See Keybindings section below for the full list of default keybindings
  add_default_keybindings = true,

  -- Command aliases for convenient shortcuts
  -- Example: using ':PickMe grep' will call ':PickMe live_grep'
  command_aliases = {
    grep = 'live_grep',
    -- Add your own aliases here
  }
})

These pickers are available across all three supported providers (snacks, telescope, fzf_lua):

• autocmds - List autocommands
• buffer_grep - Search within current buffer
• buffers - Browse and select open buffers
• colorschemes - Browse and apply colorschemes
• command_history - View command history
• commands - Browse available commands
• diagnostics - View workspace diagnostics
• files - Find files in the current directory
• git_branches - View and checkout git branches
• git_commits - Browse git commit history
• git_files - Find files tracked by Git
• git_log_file - View git commits for the current buffer
• git_log_line - View git history for current line
• git_stash - Browse git stash entries
• git_status - View files with git status changes
• grep_string - Search for the word under cursor
• help - Search through help tags
• highlights - Browse highlight groups
• jumplist - Navigate through jump history
• keymaps - Browse configured key mappings
• live_grep - Search for a string in your project (grep)
• loclist - Browse location list
• lsp_declarations - Find declarations with LSP
• lsp_definitions - Go to definition of the symbol under cursor
• lsp_document_symbols - List symbols in current document
• lsp_implementations - Find implementations of the interface under cursor
• lsp_references - Find references to the symbol under cursor
• lsp_type_definitions - Find type definitions
• lsp_workspace_symbols - Search for workspace symbols
• man - Browse manual pages
• marks - View and jump to marks
• oldfiles - Browse recently opened files
• options - Browse Neovim options
• pickers - Browse available pickers
• quickfix - Browse quickfix list
• registers - View contents of registers
• resume - Resume the last picker
• search_history - View search history
• spell_suggest - Get spelling suggestions for word under cursor
• treesitter - Navigate treesitter symbols

• cliphist - Browse clipboard history
• grep_buffers - Search across all open buffers
• icons - Browse and insert icons
• lazy - Search through lazy.nvim plugin specs
• lsp_config - Browse LSP server configurations
• projects - Browse and switch between projects

• options - View Neovim options
• icons - Browse symbols (with devicons)
• tags - Work with ctags

• breakpoints - View DAP debugger breakpoints
• git_tags - Browse git tags
• options - View Neovim options
• profiles - Switch FZF profiles
• tabs - Browse and switch between tabs
• tags - Work with ctags
• tmux_cliphist - Browse tmux clipboard history

These are utility functions you can use to create your own pickers:

• select_file - Custom file picker with provided items
• custom_picker - Fully customizable picker with custom items and handlers

local pickme = require('pickme')

-- Basic usage
pickme.pick('files', { title = 'Find Files' })
pickme.pick('live_grep', { title = 'Search Text' })

-- Select file from a list of files
pickme.select_file({
  items = { "path/to/file1.txt", "path/to/file2.lua", "path/to/file3.md" },
  title = "Select a file to open"
})

-- Using custom picker
pickme.custom_picker({
  title = 'My Custom Picker',
  items = {'item1', 'item2', 'item3'},
  entry_maker = function(item)
    return { display = item, value = item }
  end,
  preview_generator = function(item)
    return "Preview content for " .. item
  end,
  preview_ft = 'markdown',
  -- Action to perform on selection / when <CR> is pressed
  selection_handler = function(_, selection)
    print("Selected: " .. selection.value)
  end,
  -- Optional custom actions mapped to keys
  action_map = {
    ['<C-s>'] = function(_, selection)
      vim.notify("Selection: " .. selection.value)
    end
  }
})

Example Usages:

• custom_picker in octohub.nvim/repos.lua
• select_file in tdo.nvim/init.lua

If add_default_keybindings = true in your setup, the following keybindings will be automatically configured:

If you want to disable the default keybindings, set add_default_keybindings = false in your setup.

You can add your own keybindings by using the pickme.pick function or the PickMe command. For example:

local pickme = require('pickme')

vim.keymap.set('n', '<leader>ff', function() pickme.pick('git_files', { title = 'Git Files' }) end, { desc = 'Git Files' })
vim.keymap.set('n', '<leader>fg', function() pickme.pick('live_grep') end, { desc = 'Live Grep' })
vim.keymap.set('n', '<leader>fa', ':PickMe files<cr>', { desc = 'All Files' })

Run :help pickme.txt for more details.

• You tell me!

I was tired of maintaining separate implementations for different picker plugins in my Neovim extensions. Now I can write the code once and let users pick their preferred UI!

• Finding information about different pickers supported by picker providers was time consuming.
• Got to create a unified interface for different pickers.

• dots2k — Dev Environment
• nvim2k — Personalized Editor
• sway2k — Desktop Environment
• qute2k — Personalized Browser

• nerdy.nvim — Find nerd glyphs easily
• tdo.nvim — Fast and simple notes in Neovim
• termim.nvim — Neovim terminal improved
• octohub.nvim — Github repos in Neovim
• exercism.nvim — Exercism exercises in Neovim