snacks.nvim/docs/picker.md

🍿 picker

Snacks now comes with a modern fuzzy-finder to navigate the Neovim universe.

✨ Features

• 🔎 over 40 built-in sources
• 🚀 Fast and powerful fuzzy matching engine that supports the fzf search syntax
  • additionally supports field searches like file:lua$ 'function
  • files and grep additionally support adding optiont like foo -- -e=lua
• 🌲 uses treesitter highlighting where it makes sense
• 🧹 Sane default settings so you can start using it right away
• 💪 Finders and matchers run asynchronously for maximum performance
• 🪟 Different layouts to suit your needs, or create your own. Uses Snacks.layout under the hood.
• 💻 Simple API to create your own pickers
• 📋 Better vim.ui.select

Some acknowledgements:

• fzf-lua
• telescope.nvim
• mini.pick

📚 Usage

The best way to get started is to copy some of the example configs below.

-- Show all pickers
Snacks.picker()

-- run files picker (all three are equivalent)
Snacks.picker.files(opts)
Snacks.picker.pick("files", opts)
Snacks.picker.pick({source = "files", ...})

📦 Setup

-- lazy.nvim
{
  "folke/snacks.nvim",
  ---@type snacks.Config
  opts = {
    picker = {
      -- your picker configuration comes here
      -- or leave it empty to use the default settings
      -- refer to the configuration section below
    }
  }
}

⚙️ Config

---@class snacks.picker.Config
---@field multi? (string|snacks.picker.Config)[]
---@field source? string source name and config to use
---@field pattern? string|fun(picker:snacks.Picker):string pattern used to filter items by the matcher
---@field search? string|fun(picker:snacks.Picker):string search string used by finders
---@field cwd? string current working directory
---@field live? boolean when true, typing will trigger live searches
---@field limit? number when set, the finder will stop after finding this number of items. useful for live searches
---@field ui_select? boolean set `vim.ui.select` to a snacks picker
--- Source definition
---@field items? snacks.picker.finder.Item[] items to show instead of using a finder
---@field format? string|snacks.picker.format|string format function or preset
---@field finder? string|snacks.picker.finder|snacks.picker.finder.multi finder function or preset
---@field preview? snacks.picker.preview|string preview function or preset
---@field matcher? snacks.picker.matcher.Config matcher config
---@field sort? snacks.picker.sort|snacks.picker.sort.Config sort function or config
---@field transform? string|snacks.picker.transform transform/filter function
--- UI
---@field win? snacks.picker.win.Config
---@field layout? snacks.picker.layout.Config|string|{}|fun(source:string):(snacks.picker.layout.Config|string)
---@field icons? snacks.picker.icons
---@field prompt? string prompt text / icon
---@field title? string defaults to a capitalized source name
--- Preset options
---@field previewers? snacks.picker.previewers.Config|{}
---@field formatters? snacks.picker.formatters.Config|{}
---@field sources? snacks.picker.sources.Config|{}|table<string, snacks.picker.Config|{}>
---@field layouts? table<string, snacks.picker.layout.Config>
--- Actions
---@field actions? table<string, snacks.picker.Action.spec> actions used by keymaps
---@field confirm? snacks.picker.Action.spec shortcut for confirm action
---@field auto_confirm? boolean automatically confirm if there is only one item
---@field main? snacks.picker.main.Config main editor window config
---@field on_change? fun(picker:snacks.Picker, item?:snacks.picker.Item) called when the cursor changes
---@field on_show? fun(picker:snacks.Picker) called when the picker is shown
---@field jump? snacks.picker.jump.Config|{}
--- Other
---@field debug? snacks.picker.debug|{}
{
  prompt = " ",
  sources = {},
  layout = {
    cycle = true,
    --- Use the default layout or vertical if the window is too narrow
    preset = function()
      return vim.o.columns >= 120 and "default" or "vertical"
    end,
  },
  ---@class snacks.picker.matcher.Config
  matcher = {
    fuzzy = true, -- use fuzzy matching
    smartcase = true, -- use smartcase
    ignorecase = true, -- use ignorecase
    sort_empty = false, -- sort results when the search string is empty
    filename_bonus = true, -- give bonus for matching file names (last part of the path)
    file_pos = true, -- support patterns like `file:line:col` and `file:line`
    -- the bonusses below, possibly require string concatenation and path normalization,
    -- so this can have a performance impact for large lists and increase memory usage
    cwd_bonus = false, -- give bonus for matching files in the cwd
    frecency = false, -- frecency bonus
  },
  sort = {
    -- default sort is by score, text length and index
    fields = { "score:desc", "#text", "idx" },
  },
  ui_select = true, -- replace `vim.ui.select` with the snacks picker
  ---@class snacks.picker.formatters.Config
  formatters = {
    text = {
      ft = nil, ---@type string? filetype for highlighting
    },
    file = {
      filename_first = false, -- display filename before the file path
    },
    selected = {
      show_always = false, -- only show the selected column when there are multiple selections
      unselected = true, -- use the unselected icon for unselected items
    },
  },
  ---@class snacks.picker.previewers.Config
  previewers = {
    git = {
      native = false, -- use native (terminal) or Neovim for previewing git diffs and commits
    },
    file = {
      max_size = 1024 * 1024, -- 1MB
      max_line_length = 500, -- max line length
      ft = nil, ---@type string? filetype for highlighting. Use `nil` for auto detect
    },
    man_pager = nil, ---@type string? MANPAGER env to use for `man` preview
  },
  ---@class snacks.picker.jump.Config
  jump = {
    jumplist = true, -- save the current position in the jumplist
    tagstack = false, -- save the current position in the tagstack
    reuse_win = false, -- reuse an existing window if the buffer is already open
  },
  win = {
    -- input window
    input = {
      keys = {
        ["<Esc>"] = "close",
        ["<C-c>"] = { "close", mode = "i" },
        -- to close the picker on ESC instead of going to normal mode,
        -- add the following keymap to your config
        -- ["<Esc>"] = { "close", mode = { "n", "i" } },
        ["<CR>"] = { "confirm", mode = { "n", "i" } },
        ["G"] = "list_bottom",
        ["gg"] = "list_top",
        ["j"] = "list_down",
        ["k"] = "list_up",
        ["/"] = "toggle_focus",
        ["q"] = "close",
        ["?"] = "toggle_help",
        ["<a-d>"] = { "inspect", mode = { "n", "i" } },
        ["<c-a>"] = { "select_all", mode = { "n", "i" } },
        ["<a-m>"] = { "toggle_maximize", mode = { "i", "n" } },
        ["<a-p>"] = { "toggle_preview", mode = { "i", "n" } },
        ["<a-w>"] = { "cycle_win", mode = { "i", "n" } },
        ["<C-w>"] = { "<c-s-w>", mode = { "i" }, expr = true, desc = "delete word" },
        ["<C-Up>"] = { "history_back", mode = { "i", "n" } },
        ["<C-Down>"] = { "history_forward", mode = { "i", "n" } },
        ["<Tab>"] = { "select_and_next", mode = { "i", "n" } },
        ["<S-Tab>"] = { "select_and_prev", mode = { "i", "n" } },
        ["<Down>"] = { "list_down", mode = { "i", "n" } },
        ["<Up>"] = { "list_up", mode = { "i", "n" } },
        ["<c-j>"] = { "list_down", mode = { "i", "n" } },
        ["<c-k>"] = { "list_up", mode = { "i", "n" } },
        ["<c-n>"] = { "list_down", mode = { "i", "n" } },
        ["<c-p>"] = { "list_up", mode = { "i", "n" } },
        ["<c-l>"] = { "preview_scroll_left", mode = { "i", "n" } },
        ["<c-h>"] = { "preview_scroll_right", mode = { "i", "n" } },
        ["<c-b>"] = { "preview_scroll_up", mode = { "i", "n" } },
        ["<c-d>"] = { "list_scroll_down", mode = { "i", "n" } },
        ["<c-f>"] = { "preview_scroll_down", mode = { "i", "n" } },
        ["<c-g>"] = { "toggle_live", mode = { "i", "n" } },
        ["<c-u>"] = { "list_scroll_up", mode = { "i", "n" } },
        ["<ScrollWheelDown>"] = { "list_scroll_wheel_down", mode = { "i", "n" } },
        ["<ScrollWheelUp>"] = { "list_scroll_wheel_up", mode = { "i", "n" } },
        ["<c-v>"] = { "edit_vsplit", mode = { "i", "n" } },
        ["<c-s>"] = { "edit_split", mode = { "i", "n" } },
        ["<c-q>"] = { "qflist", mode = { "i", "n" } },
        ["<a-i>"] = { "toggle_ignored", mode = { "i", "n" } },
        ["<a-h>"] = { "toggle_hidden", mode = { "i", "n" } },
        ["<a-f>"] = { "toggle_follow", mode = { "i", "n" } },
      },
      b = {
        minipairs_disable = true,
      },
    },
    -- result list window
    list = {
      keys = {
        ["<CR>"] = "confirm",
        ["gg"] = "list_top",
        ["G"] = "list_bottom",
        ["i"] = "focus_input",
        ["j"] = "list_down",
        ["k"] = "list_up",
        ["q"] = "close",
        ["<Tab>"] = "select_and_next",
        ["<S-Tab>"] = "select_and_prev",
        ["<Down>"] = "list_down",
        ["<Up>"] = "list_up",
        ["<a-d>"] = "inspect",
        ["<c-d>"] = "list_scroll_down",
        ["<c-u>"] = "list_scroll_up",
        ["zt"] = "list_scroll_top",
        ["zb"] = "list_scroll_bottom",
        ["zz"] = "list_scroll_center",
        ["/"] = "toggle_focus",
        ["<ScrollWheelDown>"] = "list_scroll_wheel_down",
        ["<ScrollWheelUp>"] = "list_scroll_wheel_up",
        ["<c-a>"] = "select_all",
        ["<c-f>"] = "preview_scroll_down",
        ["<c-b>"] = "preview_scroll_up",
        ["<c-l>"] = "preview_scroll_right",
        ["<c-h>"] = "preview_scroll_left",
        ["<c-v>"] = "edit_vsplit",
        ["<c-s>"] = "edit_split",
        ["<c-j>"] = "list_down",
        ["<c-k>"] = "list_up",
        ["<c-n>"] = "list_down",
        ["<c-p>"] = "list_up",
        ["<a-w>"] = "cycle_win",
        ["<Esc>"] = "close",
      },
      wo = {
        conceallevel = 2,
        concealcursor = "nvc",
      },
    },
    -- preview window
    preview = {
      keys = {
        ["<Esc>"] = "close",
        ["q"] = "close",
        ["i"] = "focus_input",
        ["<ScrollWheelDown>"] = "list_scroll_wheel_down",
        ["<ScrollWheelUp>"] = "list_scroll_wheel_up",
        ["<a-w>"] = "cycle_win",
      },
    },
  },
  ---@class snacks.picker.icons
  icons = {
    files = {
      enabled = true, -- show file icons
    },
    keymaps = {
      nowait = "󰓅 "
    },
    indent = {
      vertical    = "│ ",
      middle = "├╴",
      last   = "└╴",
    },
    undo = {
      saved   = " ",
    },
    ui = {
      live        = "󰐰 ",
      hidden      = "h",
      ignored     = "i",
      follow      = "f",
      selected    = "● ",
      unselected  = "○ ",
      -- selected = " ",
    },
    git = {
      commit = "󰜘 ",
    },
    diagnostics = {
      Error = " ",
      Warn  = " ",
      Hint  = " ",
      Info  = " ",
    },
    kinds = {
      Array         = " ",
      Boolean       = "󰨙 ",
      Class         = " ",
      Color         = " ",
      Control       = " ",
      Collapsed     = " ",
      Constant      = "󰏿 ",
      Constructor   = " ",
      Copilot       = " ",
      Enum          = " ",
      EnumMember    = " ",
      Event         = " ",
      Field         = " ",
      File          = " ",
      Folder        = " ",
      Function      = "󰊕 ",
      Interface     = " ",
      Key           = " ",
      Keyword       = " ",
      Method        = "󰊕 ",
      Module        = " ",
      Namespace     = "󰦮 ",
      Null          = " ",
      Number        = "󰎠 ",
      Object        = " ",
      Operator      = " ",
      Package       = " ",
      Property      = " ",
      Reference     = " ",
      Snippet       = "󱄽 ",
      String        = " ",
      Struct        = "󰆼 ",
      Text          = " ",
      TypeParameter = " ",
      Unit          = " ",
      Unknown        = " ",
      Value         = " ",
      Variable      = "󰀫 ",
    },
  },
  ---@class snacks.picker.debug
  debug = {
    scores = false, -- show scores in the list
    leaks = false, -- show when pickers don't get garbage collected
  },
}

🚀 Examples

general

{
  "folke/snacks.nvim",
  opts = {
    picker = {},
  },
  keys = {
    { "<leader>,", function() Snacks.picker.buffers() end, desc = "Buffers" },
    { "<leader>/", function() Snacks.picker.grep() end, desc = "Grep" },
    { "<leader>:", function() Snacks.picker.command_history() end, desc = "Command History" },
    { "<leader><space>", function() Snacks.picker.files() end, desc = "Find Files" },
    -- find
    { "<leader>fb", function() Snacks.picker.buffers() end, desc = "Buffers" },
    { "<leader>fc", function() Snacks.picker.files({ cwd = vim.fn.stdpath("config") }) end, desc = "Find Config File" },
    { "<leader>ff", function() Snacks.picker.files() end, desc = "Find Files" },
    { "<leader>fg", function() Snacks.picker.git_files() end, desc = "Find Git Files" },
    { "<leader>fr", function() Snacks.picker.recent() end, desc = "Recent" },
    -- git
    { "<leader>gc", function() Snacks.picker.git_log() end, desc = "Git Log" },
    { "<leader>gs", function() Snacks.picker.git_status() end, desc = "Git Status" },
    -- Grep
    { "<leader>sb", function() Snacks.picker.lines() end, desc = "Buffer Lines" },
    { "<leader>sB", function() Snacks.picker.grep_buffers() end, desc = "Grep Open Buffers" },
    { "<leader>sg", function() Snacks.picker.grep() end, desc = "Grep" },
    { "<leader>sw", function() Snacks.picker.grep_word() end, desc = "Visual selection or word", mode = { "n", "x" } },
    -- search
    { '<leader>s"', function() Snacks.picker.registers() end, desc = "Registers" },
    { "<leader>sa", function() Snacks.picker.autocmds() end, desc = "Autocmds" },
    { "<leader>sc", function() Snacks.picker.command_history() end, desc = "Command History" },
    { "<leader>sC", function() Snacks.picker.commands() end, desc = "Commands" },
    { "<leader>sd", function() Snacks.picker.diagnostics() end, desc = "Diagnostics" },
    { "<leader>sh", function() Snacks.picker.help() end, desc = "Help Pages" },
    { "<leader>sH", function() Snacks.picker.highlights() end, desc = "Highlights" },
    { "<leader>sj", function() Snacks.picker.jumps() end, desc = "Jumps" },
    { "<leader>sk", function() Snacks.picker.keymaps() end, desc = "Keymaps" },
    { "<leader>sl", function() Snacks.picker.loclist() end, desc = "Location List" },
    { "<leader>sM", function() Snacks.picker.man() end, desc = "Man Pages" },
    { "<leader>sm", function() Snacks.picker.marks() end, desc = "Marks" },
    { "<leader>sR", function() Snacks.picker.resume() end, desc = "Resume" },
    { "<leader>sq", function() Snacks.picker.qflist() end, desc = "Quickfix List" },
    { "<leader>uC", function() Snacks.picker.colorschemes() end, desc = "Colorschemes" },
    { "<leader>qp", function() Snacks.picker.projects() end, desc = "Projects" },
    -- LSP
    { "gd", function() Snacks.picker.lsp_definitions() end, desc = "Goto Definition" },
    { "gr", function() Snacks.picker.lsp_references() end, nowait = true, desc = "References" },
    { "gI", function() Snacks.picker.lsp_implementations() end, desc = "Goto Implementation" },
    { "gy", function() Snacks.picker.lsp_type_definitions() end, desc = "Goto T[y]pe Definition" },
    { "<leader>ss", function() Snacks.picker.lsp_symbols() end, desc = "LSP Symbols" },
  },
}

todo_comments

{
  "folke/todo-comments.nvim",
  optional = true,
  keys = {
    { "<leader>st", function() Snacks.picker.todo_comments() end, desc = "Todo" },
    { "<leader>sT", function () Snacks.picker.todo_comments({ keywords = { "TODO", "FIX", "FIXME" } }) end, desc = "Todo/Fix/Fixme" },
  },
}

trouble

{
  "folke/trouble.nvim",
  optional = true,
  specs = {
    "folke/snacks.nvim",
    opts = function(_, opts)
      return vim.tbl_deep_extend("force", opts or {}, {
        picker = {
          actions = require("trouble.sources.snacks").actions,
          win = {
            input = {
              keys = {
                ["<c-t>"] = {
                  "trouble_open",
                  mode = { "n", "i" },
                },
              },
            },
          },
        },
      })
    end,
  },
}

📚 Types

---@class snacks.picker.jump.Action: snacks.picker.Action
---@field cmd? string

---@alias snacks.picker.Extmark vim.api.keyset.set_extmark|{col:number, row?:number, field?:string}
---@alias snacks.picker.Text {[1]:string, [2]:string?, virtual?:boolean, field?:string}
---@alias snacks.picker.Highlight snacks.picker.Text|snacks.picker.Extmark
---@alias snacks.picker.format fun(item:snacks.picker.Item, picker:snacks.Picker):snacks.picker.Highlight[]
---@alias snacks.picker.preview fun(ctx: snacks.picker.preview.ctx):boolean?
---@alias snacks.picker.sort fun(a:snacks.picker.Item, b:snacks.picker.Item):boolean
---@alias snacks.picker.transform fun(item:snacks.picker.finder.Item, ctx:snacks.picker.finder.ctx):(boolean|snacks.picker.finder.Item|nil)
---@alias snacks.picker.Pos {[1]:number, [2]:number}

Generic filter used by finders to pre-filter items

---@class snacks.picker.filter.Config
---@field cwd? boolean|string only show files for the given cwd
---@field buf? boolean|number only show items for the current or given buffer
---@field paths? table<string, boolean> only show items that include or exclude the given paths
---@field filter? fun(item:snacks.picker.finder.Item, filter:snacks.picker.Filter):boolean? custom filter function
---@field transform? fun(picker:snacks.Picker, filter:snacks.picker.Filter):boolean? filter transform. Return `true` to force refresh

This is only used when using opts.preview = "preview". It's a previewer that shows a preview based on the item data.

---@class snacks.picker.Item.preview
---@field text string text to show in the preview buffer
---@field ft? string optional filetype used tohighlight the preview buffer
---@field extmarks? snacks.picker.Extmark[] additional extmarks
---@field loc? boolean set to false to disable showing the item location in the preview

---@class snacks.picker.Item
---@field [string] any
---@field idx number
---@field score number
---@field frecency? number
---@field score_add? number
---@field score_mul? number
---@field match_tick? number
---@field source_id? number
---@field file? string
---@field text string
---@field pos? snacks.picker.Pos
---@field loc? snacks.picker.lsp.Loc
---@field end_pos? snacks.picker.Pos
---@field highlights? snacks.picker.Highlight[][]
---@field preview? snacks.picker.Item.preview
---@field resolve? fun(item:snacks.picker.Item)

---@class snacks.picker.finder.Item: snacks.picker.Item
---@field idx? number
---@field score? number

---@class snacks.picker.layout.Config
---@field layout snacks.layout.Box
---@field reverse? boolean when true, the list will be reversed (bottom-up)
---@field fullscreen? boolean open in fullscreen
---@field cycle? boolean cycle through the list
---@field preview? boolean|"main" show preview window in the picker or the main window
---@field preset? string|fun(source:string):string

---@class snacks.picker.win.Config
---@field input? snacks.win.Config|{} input window config
---@field list? snacks.win.Config|{} result list window config
---@field preview? snacks.win.Config|{} preview window config

---@alias snacks.Picker.ref (fun():snacks.Picker?)|{value?: snacks.Picker}

---@class snacks.picker.Last
---@field cursor number
---@field topline number
---@field opts? snacks.picker.Config
---@field selected snacks.picker.Item[]
---@field filter snacks.picker.Filter

---@alias snacks.picker.history.Record {pattern: string, search: string, live?: boolean}

📦 Module

---@class snacks.picker
---@field actions snacks.picker.actions
---@field config snacks.picker.config
---@field format snacks.picker.formatters
---@field preview snacks.picker.previewers
---@field sort snacks.picker.sorters
---@field util snacks.picker.util
---@field current? snacks.Picker
---@field highlight snacks.picker.highlight
---@field resume fun(opts?: snacks.picker.Config):snacks.Picker
---@field sources snacks.picker.sources.Config
Snacks.picker = {}

Snacks.picker()

---@type fun(source: string, opts: snacks.picker.Config): snacks.Picker
Snacks.picker()

---@type fun(opts: snacks.picker.Config): snacks.Picker
Snacks.picker()

Snacks.picker.pick()

Create a new picker

---@param source? string
---@param opts? snacks.picker.Config
---@overload fun(opts: snacks.picker.Config): snacks.Picker
Snacks.picker.pick(source, opts)

Snacks.picker.select()

Implementation for vim.ui.select

---@type snacks.picker.ui_select
Snacks.picker.select(...)

🔍 Sources

autocmds

:lua Snacks.picker.autocmds(opts?)

{
  finder = "vim_autocmds",
  format = "autocmd",
  preview = "preview",
}

buffers

:lua Snacks.picker.buffers(opts?)

---@class snacks.picker.buffers.Config: snacks.picker.Config
---@field hidden? boolean show hidden buffers (unlisted)
---@field unloaded? boolean show loaded buffers
---@field current? boolean show current buffer
---@field nofile? boolean show `buftype=nofile` buffers
---@field sort_lastused? boolean sort by last used
---@field filter? snacks.picker.filter.Config
{
  finder = "buffers",
  format = "buffer",
  hidden = false,
  unloaded = true,
  current = true,
  sort_lastused = true,
  win = {
    input = {
      keys = {
        ["dd"] = "bufdelete",
        ["<c-x>"] = { "bufdelete", mode = { "n", "i" } },
      },
    },
    list = { keys = { ["dd"] = "bufdelete" } },
  },
}

cliphist

:lua Snacks.picker.cliphist(opts?)

{
  finder = "system_cliphist",
  format = "text",
  preview = "preview",
  confirm = { "copy", "close" },
}

colorschemes

:lua Snacks.picker.colorschemes(opts?)

Neovim colorschemes with live preview

{
  finder = "vim_colorschemes",
  format = "text",
  preview = "colorscheme",
  preset = "vertical",
  confirm = function(picker, item)
    picker:close()
    if item then
      picker.preview.state.colorscheme = nil
      vim.schedule(function()
        vim.cmd("colorscheme " .. item.text)
      end)
    end
  end,
}

command_history

:lua Snacks.picker.command_history(opts?)

Neovim command history

---@type snacks.picker.history.Config
{
  finder = "vim_history",
  name = "cmd",
  format = "text",
  preview = "none",
  layout = {
    preset = "vscode",
  },
  confirm = "cmd",
  formatters = { text = { ft = "vim" } },
}

commands

:lua Snacks.picker.commands(opts?)

Neovim commands

{
  finder = "vim_commands",
  format = "command",
  preview = "preview",
  confirm = "cmd",
}

diagnostics

:lua Snacks.picker.diagnostics(opts?)

---@class snacks.picker.diagnostics.Config: snacks.picker.Config
---@field filter? snacks.picker.filter.Config
---@field severity? vim.diagnostic.SeverityFilter
{
  finder = "diagnostics",
  format = "diagnostic",
  sort = {
    fields = {
      "is_current",
      "is_cwd",
      "severity",
      "file",
      "lnum",
    },
  },
  matcher = { sort_empty = true },
  -- only show diagnostics from the cwd by default
  filter = { cwd = true },
}

diagnostics_buffer

:lua Snacks.picker.diagnostics_buffer(opts?)

---@type snacks.picker.diagnostics.Config
{
  finder = "diagnostics",
  format = "diagnostic",
  sort = {
    fields = { "severity", "file", "lnum" },
  },
  matcher = { sort_empty = true },
  filter = { buf = true },
}

files

:lua Snacks.picker.files(opts?)

---@class snacks.picker.files.Config: snacks.picker.proc.Config
---@field cmd? string
---@field hidden? boolean show hidden files
---@field ignored? boolean show ignored files
---@field dirs? string[] directories to search
---@field follow? boolean follow symlinks
---@field exclude? string[] exclude patterns
---@field args? string[] additional arguments
{
  finder = "files",
  format = "file",
  hidden = false,
  ignored = false,
  follow = false,
  supports_live = true,
}

git_branches

:lua Snacks.picker.git_branches(opts?)

{
  finder = "git_branches",
  format = "git_branch",
  preview = "git_log",
  confirm = "git_checkout",
  on_show = function(picker)
    for i, item in ipairs(picker:items()) do
      if item.current then
        picker.list:view(i)
        Snacks.picker.actions.list_scroll_center(picker)
        break
      end
    end
  end,
}

git_diff

:lua Snacks.picker.git_diff(opts?)

{
  finder = "git_diff",
  format = "file",
  preview = "preview",
}

git_files

:lua Snacks.picker.git_files(opts?)

Find git files

---@class snacks.picker.git.files.Config: snacks.picker.Config
---@field untracked? boolean show untracked files
---@field submodules? boolean show submodule files
{
  finder = "git_files",
  format = "file",
  untracked = false,
  submodules = false,
}

git_log

:lua Snacks.picker.git_log(opts?)

Git log

---@class snacks.picker.git.log.Config: snacks.picker.Config
---@field follow? boolean track file history across renames
---@field current_file? boolean show current file log
---@field current_line? boolean show current line log
{
  finder = "git_log",
  format = "git_log",
  preview = "git_show",
  confirm = "close",
}

git_log_file

:lua Snacks.picker.git_log_file(opts?)

---@type snacks.picker.git.log.Config
{
  finder = "git_log",
  format = "git_log",
  preview = "git_show",
  current_file = true,
  follow = true,
  confirm = "close",
}

git_log_line

:lua Snacks.picker.git_log_line(opts?)

---@type snacks.picker.git.log.Config
{
  finder = "git_log",
  format = "git_log",
  preview = "git_show",
  current_line = true,
  follow = true,
  confirm = "close",
}

git_status

:lua Snacks.picker.git_status(opts?)

{
  finder = "git_status",
  format = "git_status",
  preview = "git_status",
  win = {
    input = {
      keys = {
        ["<Tab>"] = { "git_stage", mode = { "n", "i" } },
      },
    },
  },
}

grep

:lua Snacks.picker.grep(opts?)

---@class snacks.picker.grep.Config: snacks.picker.proc.Config
---@field cmd? string
---@field hidden? boolean show hidden files
---@field ignored? boolean show ignored files
---@field dirs? string[] directories to search
---@field follow? boolean follow symlinks
---@field glob? string|string[] glob file pattern(s)
---@field ft? string|string[] ripgrep file type(s). See `rg --type-list`
---@field regex? boolean use regex search pattern (defaults to `true`)
---@field buffers? boolean search in open buffers
---@field need_search? boolean require a search pattern
---@field exclude? string[] exclude patterns
---@field args? string[] additional arguments
{
  finder = "grep",
  format = "file",
  live = true, -- live grep by default
  supports_live = true,
}

grep_buffers

:lua Snacks.picker.grep_buffers(opts?)

---@type snacks.picker.grep.Config
{
  finder = "grep",
  format = "file",
  live = true,
  buffers = true,
  need_search = false,
  supports_live = true,
}

grep_word

:lua Snacks.picker.grep_word(opts?)

---@type snacks.picker.grep.Config
{
  finder = "grep",
  format = "file",
  search = function(picker)
    return picker:word()
  end,
  live = false,
  supports_live = true,
}

help

:lua Snacks.picker.help(opts?)

Neovim help tags

---@class snacks.picker.help.Config: snacks.picker.Config
---@field lang? string[] defaults to `vim.opt.helplang`
{
  finder = "help",
  format = "text",
  previewers = {
    file = { ft = "help" },
  },
  win = {
    preview = {
      minimal = true,
    },
  },
  confirm = "help",
}

highlights

:lua Snacks.picker.highlights(opts?)

{
  finder = "vim_highlights",
  format = "hl",
  preview = "preview",
}

jumps

:lua Snacks.picker.jumps(opts?)

{
  finder = "vim_jumps",
  format = "file",
}

keymaps

:lua Snacks.picker.keymaps(opts?)

---@class snacks.picker.keymaps.Config: snacks.picker.Config
---@field global? boolean show global keymaps
---@field local? boolean show buffer keymaps
---@field plugs? boolean show plugin keymaps
---@field modes? string[]
{
  finder = "vim_keymaps",
  format = "keymap",
  preview = "preview",
  global = true,
  plugs = false,
  ["local"] = true,
  modes = { "n", "v", "x", "s", "o", "i", "c", "t" },
  confirm = function(picker, item)
    picker:close()
    if item then
      vim.api.nvim_input(item.item.lhs)
    end
  end,
}

lines

:lua Snacks.picker.lines(opts?)

Search lines in the current buffer

---@class snacks.picker.lines.Config: snacks.picker.Config
---@field buf? number
{
  finder = "lines",
  format = "lines",
  layout = {
    preview = "main",
    preset = "ivy",
  },
  -- allow any window to be used as the main window
  main = { current = true },
  ---@param picker snacks.Picker
  on_show = function(picker)
    local cursor = vim.api.nvim_win_get_cursor(picker.main)
    local info = vim.api.nvim_win_call(picker.main, vim.fn.winsaveview)
    picker.list:view(cursor[1], info.topline)
    picker:show_preview()
  end,
  sort = { fields = { "score:desc", "idx" } },
}

loclist

:lua Snacks.picker.loclist(opts?)

Loclist

---@type snacks.picker.qf.Config
{
  finder = "qf",
  format = "file",
  qf_win = 0,
}

lsp_declarations

:lua Snacks.picker.lsp_declarations(opts?)

LSP declarations

---@type snacks.picker.lsp.Config
{
  finder = "lsp_declarations",
  format = "file",
  include_current = false,
  auto_confirm = true,
  jump = { tagstack = true, reuse_win = true },
}

lsp_definitions

:lua Snacks.picker.lsp_definitions(opts?)

LSP definitions

---@type snacks.picker.lsp.Config
{
  finder = "lsp_definitions",
  format = "file",
  include_current = false,
  auto_confirm = true,
  jump = { tagstack = true, reuse_win = true },
}

lsp_implementations

:lua Snacks.picker.lsp_implementations(opts?)

LSP implementations

---@type snacks.picker.lsp.Config
{
  finder = "lsp_implementations",
  format = "file",
  include_current = false,
  auto_confirm = true,
  jump = { tagstack = true, reuse_win = true },
}

lsp_references

:lua Snacks.picker.lsp_references(opts?)

LSP references

---@class snacks.picker.lsp.references.Config: snacks.picker.lsp.Config
---@field include_declaration? boolean default true
{
  finder = "lsp_references",
  format = "file",
  include_declaration = true,
  include_current = false,
  auto_confirm = true,
  jump = { tagstack = true, reuse_win = true },
}

lsp_symbols

:lua Snacks.picker.lsp_symbols(opts?)

LSP document symbols

---@class snacks.picker.lsp.symbols.Config: snacks.picker.Config
---@field hierarchy? boolean show symbol hierarchy
---@field filter table<string, string[]|boolean>? symbol kind filter
---@field workspace? boolean show workspace symbols
{
  finder = "lsp_symbols",
  format = "lsp_symbol",
  hierarchy = true,
  filter = {
    default = {
      "Class",
      "Constructor",
      "Enum",
      "Field",
      "Function",
      "Interface",
      "Method",
      "Module",
      "Namespace",
      "Package",
      "Property",
      "Struct",
      "Trait",
    },
    -- set to `true` to include all symbols
    markdown = true,
    help = true,
    -- you can specify a different filter for each filetype
    lua = {
      "Class",
      "Constructor",
      "Enum",
      "Field",
      "Function",
      "Interface",
      "Method",
      "Module",
      "Namespace",
      -- "Package", -- remove package since luals uses it for control flow structures
      "Property",
      "Struct",
      "Trait",
    },
  },
}

lsp_type_definitions

:lua Snacks.picker.lsp_type_definitions(opts?)

LSP type definitions

---@type snacks.picker.lsp.Config
{
  finder = "lsp_type_definitions",
  format = "file",
  include_current = false,
  auto_confirm = true,
  jump = { tagstack = true, reuse_win = true },
}

lsp_workspace_symbols

:lua Snacks.picker.lsp_workspace_symbols(opts?)

---@type snacks.picker.lsp.symbols.Config
vim.tbl_extend("force", {}, M.lsp_symbols, {
  workspace = true,
  hierarchy = false,
  supports_live = true,
  live = true, -- live by default
})

man

:lua Snacks.picker.man(opts?)

{
  finder = "system_man",
  format = "man",
  preview = "man",
  confirm = function(picker, item)
    picker:close()
    if item then
      vim.schedule(function()
        vim.cmd("Man " .. item.ref)
      end)
    end
  end,
}

marks

:lua Snacks.picker.marks(opts?)

---@class snacks.picker.marks.Config: snacks.picker.Config
---@field global? boolean show global marks
---@field local? boolean show buffer marks
{
  finder = "vim_marks",
  format = "file",
  global = true,
  ["local"] = true,
}

picker_actions

:lua Snacks.picker.picker_actions(opts?)

{
  finder = "meta_actions",
  format = "text",
}

picker_format

:lua Snacks.picker.picker_format(opts?)

{
  finder = "meta_format",
  format = "text",
}

picker_layouts

:lua Snacks.picker.picker_layouts(opts?)

{
  finder = "meta_layouts",
  format = "text",
  on_change = function(picker, item)
    vim.schedule(function()
      picker:set_layout(item.text)
    end)
  end,
}

picker_preview

:lua Snacks.picker.picker_preview(opts?)

{
  finder = "meta_preview",
  format = "text",
}

pickers

:lua Snacks.picker.pickers(opts?)

List all available sources

{
  finder = "meta_pickers",
  format = "text",
  confirm = function(picker, item)
    picker:close()
    if item then
      Snacks.picker(item.text)
    end
  end,
}

projects

:lua Snacks.picker.projects(opts?)

Open recent projects

---@class snacks.picker.projects.Config: snacks.picker.Config
---@field filter? snacks.picker.filter.Config
{
  finder = "recent_projects",
  format = "file",
  confirm = "load_session",
  win = {
    preview = {
      minimal = true,
    },
  },
}

qflist

:lua Snacks.picker.qflist(opts?)

Quickfix list

---@type snacks.picker.qf.Config
{
  finder = "qf",
  format = "file",
}

recent

:lua Snacks.picker.recent(opts?)

Find recent files

---@class snacks.picker.recent.Config: snacks.picker.Config
---@field filter? snacks.picker.filter.Config
{
  finder = "recent_files",
  format = "file",
  filter = {
    paths = {
      [vim.fn.stdpath("data")] = false,
      [vim.fn.stdpath("cache")] = false,
      [vim.fn.stdpath("state")] = false,
    },
  },
}

registers

:lua Snacks.picker.registers(opts?)

Neovim registers

{
  finder = "vim_registers",
  format = "register",
  preview = "preview",
  confirm = { "copy", "close" },
}

resume

:lua Snacks.picker.resume(opts?)

Special picker that resumes the last picker

{}

search_history

:lua Snacks.picker.search_history(opts?)

Neovim search history

---@type snacks.picker.history.Config
{
  finder = "vim_history",
  name = "search",
  format = "text",
  preview = "none",
  layout = { preset = "vscode" },
  confirm = "search",
  formatters = { text = { ft = "regex" } },
}

smart

:lua Snacks.picker.smart(opts?)

---@class snacks.picker.smart.Config: snacks.picker.Config
---@field finders? string[] list of finders to use
---@field filter? snacks.picker.filter.Config
{
  multi = { "buffers", "recent", "files" },
  format = "file", -- use `file` format for all sources
  matcher = {
    cwd_bonus = true, -- boost cwd matches
    frecency = true, -- use frecency boosting
    sort_empty = true, -- sort even when the filter is empty
  },
  transform = "unique_file",
}

spelling

:lua Snacks.picker.spelling(opts?)

{
  finder = "vim_spelling",
  format = "text",
  layout = { preset = "vscode" },
  confirm = "item_action",
}

undo

:lua Snacks.picker.undo(opts?)

{
  finder = "vim_undo",
  format = "undo",
  preview = "preview",
  confirm = "item_action",
  win = { preview = { wo = { number = false, relativenumber = false, signcolumn = "no" } } },
}

zoxide

:lua Snacks.picker.zoxide(opts?)

Open a project from zoxide

{
  finder = "files_zoxide",
  format = "file",
  confirm = "load_session",
  win = {
    preview = {
      minimal = true,
    },
  },
}

🖼️ Layouts

default

{
  layout = {
    box = "horizontal",
    width = 0.8,
    min_width = 120,
    height = 0.8,
    {
      box = "vertical",
      border = "rounded",
      title = "{title} {live} {flags}",
      { win = "input", height = 1, border = "bottom" },
      { win = "list", border = "none" },
    },
    { win = "preview", title = "{preview}", border = "rounded", width = 0.5 },
  },
}

dropdown

{
  layout = {
    backdrop = false,
    row = 1,
    width = 0.4,
    min_width = 80,
    height = 0.8,
    border = "none",
    box = "vertical",
    { win = "preview", title = "{preview}", height = 0.4, border = "rounded" },
    {
      box = "vertical",
      border = "rounded",
      title = "{title} {live} {flags}",
      title_pos = "center",
      { win = "input", height = 1, border = "bottom" },
      { win = "list", border = "none" },
    },
  },
}

ivy

{
  layout = {
    box = "vertical",
    backdrop = false,
    row = -1,
    width = 0,
    height = 0.4,
    border = "top",
    title = " {title} {live} {flags}",
    title_pos = "left",
    { win = "input", height = 1, border = "bottom" },
    {
      box = "horizontal",
      { win = "list", border = "none" },
      { win = "preview", title = "{preview}", width = 0.6, border = "left" },
    },
  },
}

select

{
  preview = false,
  layout = {
    backdrop = false,
    width = 0.5,
    min_width = 80,
    height = 0.4,
    min_height = 10,
    box = "vertical",
    border = "rounded",
    title = " Select ",
    title_pos = "center",
    { win = "input", height = 1, border = "bottom" },
    { win = "list", border = "none" },
    { win = "preview", title = "{preview}", height = 0.4, border = "top" },
  },
}

telescope

{
  reverse = true,
  layout = {
    box = "horizontal",
    backdrop = false,
    width = 0.8,
    height = 0.9,
    border = "none",
    {
      box = "vertical",
      { win = "list", title = " Results ", title_pos = "center", border = "rounded" },
      { win = "input", height = 1, border = "rounded", title = "{title} {live} {flags}", title_pos = "center" },
    },
    {
      win = "preview",
      title = "{preview:Preview}",
      width = 0.45,
      border = "rounded",
      title_pos = "center",
    },
  },
}

vertical

{
  layout = {
    backdrop = false,
    width = 0.5,
    min_width = 80,
    height = 0.8,
    min_height = 30,
    box = "vertical",
    border = "rounded",
    title = "{title} {live} {flags}",
    title_pos = "center",
    { win = "input", height = 1, border = "bottom" },
    { win = "list", border = "none" },
    { win = "preview", title = "{preview}", height = 0.4, border = "top" },
  },
}

vscode

{
  preview = false,
  layout = {
    backdrop = false,
    row = 1,
    width = 0.4,
    min_width = 80,
    height = 0.4,
    border = "none",
    box = "vertical",
    { win = "input", height = 1, border = "rounded", title = "{title} {live} {flags}", title_pos = "center" },
    { win = "list", border = "hpad" },
    { win = "preview", title = "{preview}", border = "rounded" },
  },
}

📦 snacks.picker.actions

---@class snacks.picker.actions
---@field [string] snacks.picker.Action.spec
local M = {}

Snacks.picker.actions.bufdelete()

Snacks.picker.actions.bufdelete(picker)

Snacks.picker.actions.cmd()

Snacks.picker.actions.cmd(picker, item)

Snacks.picker.actions.copy()

Snacks.picker.actions.copy(_, item)

Snacks.picker.actions.cycle_win()

Snacks.picker.actions.cycle_win(picker)

Snacks.picker.actions.focus_input()

Snacks.picker.actions.focus_input(picker)

Snacks.picker.actions.focus_list()

Snacks.picker.actions.focus_list(picker)

Snacks.picker.actions.focus_preview()

Snacks.picker.actions.focus_preview(picker)

Snacks.picker.actions.git_checkout()

Snacks.picker.actions.git_checkout(picker, item)

Snacks.picker.actions.git_stage()

Snacks.picker.actions.git_stage(picker)

Snacks.picker.actions.help()

Snacks.picker.actions.help(picker)

Snacks.picker.actions.history_back()

Snacks.picker.actions.history_back(picker)

Snacks.picker.actions.history_forward()

Snacks.picker.actions.history_forward(picker)

Snacks.picker.actions.inspect()

Snacks.picker.actions.inspect(picker, item)

Snacks.picker.actions.item_action()

Snacks.picker.actions.item_action(picker, item, action)

Snacks.picker.actions.jump()

Snacks.picker.actions.jump(picker, _, action)

Snacks.picker.actions.list_bottom()

Snacks.picker.actions.list_bottom(picker)

Snacks.picker.actions.list_down()

Snacks.picker.actions.list_down(picker)

Snacks.picker.actions.list_scroll_bottom()

Snacks.picker.actions.list_scroll_bottom(picker)

Snacks.picker.actions.list_scroll_center()

Snacks.picker.actions.list_scroll_center(picker)

Snacks.picker.actions.list_scroll_down()

Snacks.picker.actions.list_scroll_down(picker)

Snacks.picker.actions.list_scroll_top()

Snacks.picker.actions.list_scroll_top(picker)

Snacks.picker.actions.list_scroll_up()

Snacks.picker.actions.list_scroll_up(picker)

Snacks.picker.actions.list_scroll_wheel_down()

Snacks.picker.actions.list_scroll_wheel_down(picker)

Snacks.picker.actions.list_scroll_wheel_up()

Snacks.picker.actions.list_scroll_wheel_up(picker)

Snacks.picker.actions.list_top()

Snacks.picker.actions.list_top(picker)

Snacks.picker.actions.list_up()

Snacks.picker.actions.list_up(picker)

Snacks.picker.actions.load_session()

Tries to load the session, if it fails, it will open the picker.

Snacks.picker.actions.load_session(picker)

Snacks.picker.actions.loclist()

Send selected or all items to the location list.

Snacks.picker.actions.loclist(picker)

Snacks.picker.actions.preview_scroll_down()

Snacks.picker.actions.preview_scroll_down(picker)

Snacks.picker.actions.preview_scroll_left()

Snacks.picker.actions.preview_scroll_left(picker)

Snacks.picker.actions.preview_scroll_right()

Snacks.picker.actions.preview_scroll_right(picker)

Snacks.picker.actions.preview_scroll_up()

Snacks.picker.actions.preview_scroll_up(picker)

Snacks.picker.actions.qflist()

Send selected or all items to the quickfix list.

Snacks.picker.actions.qflist(picker)

Snacks.picker.actions.qflist_all()

Send all items to the quickfix list.

Snacks.picker.actions.qflist_all(picker)

Snacks.picker.actions.search()

Snacks.picker.actions.search(picker, item)

Snacks.picker.actions.select_all()

Selects all items in the list. Or clears the selection if all items are selected.

Snacks.picker.actions.select_all(picker)

Snacks.picker.actions.select_and_next()

Toggles the selection of the current item, and moves the cursor to the next item.

Snacks.picker.actions.select_and_next(picker)

Snacks.picker.actions.select_and_prev()

Toggles the selection of the current item, and moves the cursor to the prev item.

Snacks.picker.actions.select_and_prev(picker)

Snacks.picker.actions.toggle_focus()

Snacks.picker.actions.toggle_focus(picker)

Snacks.picker.actions.toggle_follow()

Snacks.picker.actions.toggle_follow(picker)

Snacks.picker.actions.toggle_hidden()

Snacks.picker.actions.toggle_hidden(picker)

Snacks.picker.actions.toggle_ignored()

Snacks.picker.actions.toggle_ignored(picker)

Snacks.picker.actions.toggle_live()

Snacks.picker.actions.toggle_live(picker)

Snacks.picker.actions.toggle_maximize()

Snacks.picker.actions.toggle_maximize(picker)

Snacks.picker.actions.toggle_preview()

Snacks.picker.actions.toggle_preview(picker)

📦 snacks.picker.core.picker

---@class snacks.Picker
---@field id number
---@field opts snacks.picker.Config
---@field finder snacks.picker.Finder
---@field format snacks.picker.format
---@field input snacks.picker.input
---@field layout snacks.layout
---@field resolved_layout snacks.picker.layout.Config
---@field list snacks.picker.list
---@field matcher snacks.picker.Matcher
---@field main number
---@field preview snacks.picker.Preview
---@field shown? boolean
---@field sort snacks.picker.sort
---@field updater uv.uv_timer_t
---@field start_time number
---@field title string
---@field closed? boolean
---@field history snacks.picker.History
---@field visual? snacks.picker.Visual
local M = {}

picker:action()

Execute the given action(s)

---@param actions string|string[]
picker:action(actions)

picker:close()

Close the picker

picker:close()

picker:count()

Total number of items in the picker

picker:count()

picker:current()

Get the current item at the cursor

---@param opts? {resolve?: boolean} default is `true`
picker:current(opts)

picker:cwd()

picker:cwd()

picker:empty()

Check if the picker is empty

picker:empty()

picker:filter()

Get the active filter

picker:filter()

picker:find()

Check if the finder and/or matcher need to run, based on the current pattern and search string.

---@param opts? { on_done?: fun(), refresh?: boolean }
picker:find(opts)

picker:hist()

Move the history cursor

---@param forward? boolean
picker:hist(forward)

picker:is_active()

Check if the finder or matcher is running

picker:is_active()

picker:items()

Get all filtered items in the picker.

picker:items()

picker:iter()

Returns an iterator over the filtered items in the picker. Items will be in sorted order.

---@return fun():snacks.picker.Item?
picker:iter()

picker:norm()

Execute the callback in normal mode. When still in insert mode, stop insert mode first, and thenvim.schedule the callback.

---@param cb fun()
picker:norm(cb)

picker:ref()

---@return snacks.Picker.ref
picker:ref()

picker:resolve()

---@param item snacks.picker.Item?
picker:resolve(item)

picker:selected()

Get the selected items. If fallback=true and there is no selection, return the current item.

---@param opts? {fallback?: boolean} default is `false`
---@return snacks.picker.Item[]
picker:selected(opts)

picker:set_cwd()

picker:set_cwd(cwd)

picker:set_layout()

Set the picker layout. Can be either the name of a preset layout or a custom layout configuration.

---@param layout? string|snacks.picker.layout.Config
picker:set_layout(layout)

picker:show_preview()

Show the preview. Show instantly when no item is yet in the preview, otherwise throttle the preview.

picker:show_preview()

picker:word()

Get the word under the cursor or the current visual selection

picker:word()