mirrors/snacks.nvim

Fork 0

mirror of https://github.com/folke/snacks.nvim synced 2025-07-12 07:35:08 +00:00

Folke Lemaitre 8078bb353f

docs: more docs

2025-01-14 22:44:37 +01:00

36 KiB

Raw Permalink Blame History

🍿 picker

📦 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 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? snacks.picker.format|string format function or preset
---@field finder? snacks.picker.finder|string 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
--- 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
--- Preset options
---@field previewers? snacks.picker.preview.Config
---@field sources? snacks.picker.sources.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
{
  prompt = " ",
  sources = {},
  layout = {
    cycle = true,
    preset = function()
      return vim.o.columns >= 120 and "default" or "vertical"
    end,
  },
  ui_select = true, -- replace `vim.ui.select` with the snacks picker
  previewers = {
    file = {
      max_size = 1024 * 1024, -- 1MB
      max_line_length = 500,
    },
  },
  win = {
    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",
        ["<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-f>"] = "preview_scroll_down",
        ["<c-b>"] = "preview_scroll_up",
        ["<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",
      },
    },
    input = {
      keys = {
        ["<Esc>"] = "close",
        ["<CR>"] = "confirm",
        ["G"] = "list_bottom",
        ["gg"] = "list_top",
        ["j"] = "list_down",
        ["k"] = "list_up",
        ["/"] = "toggle_focus",
        ["q"] = "close",
        ["?"] = "toggle_help",
        ["<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-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" } },
      },
      b = {
        minipairs_disable = true,
      },
    },
    preview = {
      minimal = false,
      wo = {
        cursorline = false,
        colorcolumn = "",
      },
      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 = {
    indent = {
      vertical    = "│ ",
      middle = "├╴",
      last   = "└╴",
    },
    ui = {
      live        = "󰐰 ",
      selected    = "● ",
      -- 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          = " ",
      Uknown        = " ",
      Value         = " ",
      Variable      = "󰀫 ",
    },
  },
}

🚀 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.Last
---@field opts snacks.picker.Config
---@field selected snacks.picker.Item[]
---@field filter snacks.picker.Filter

---@alias snacks.picker.Extmark vim.api.keyset.set_extmark|{col:number, row?:number}
---@alias snacks.picker.Text {[1]:string, [2]:string?, virtual?:boolean}
---@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

---@class snacks.picker.finder.Item: snacks.picker.Item
---@field idx? number
---@field score? 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):boolean custom filter function

---@class snacks.picker.Item
---@field [string] any
---@field idx number
---@field score number
---@field match_tick? number
---@field text string
---@field pos? {[1]:number, [2]:number}
---@field end_pos? {[1]:number, [2]:number}
---@field highlights? snacks.picker.Highlight[][]

---@class snacks.picker.sources.Config

---@class snacks.picker.preview.Config
---@field man_pager? string MANPAGER env to use for `man` preview
---@field file snacks.picker.preview.file.Config

---@class snacks.picker.preview.file.Config
---@field max_size? number default 1MB
---@field max_line_length? number defaults to 500
---@field ft? string defaults to auto-detect

---@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|{}
---@field list? snacks.win.Config|{}
---@field preview? snacks.win.Config|{}

📦 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`

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

`buffers`

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

`cliphist`

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

`colorschemes`

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`

Neovim command history

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

`commands`

Neovim commands

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

`diagnostics`

---@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",
    },
  },
  -- only show diagnostics from the cwd by default
  filter = { cwd = true },
}

`diagnostics_buffer`

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

`files`

---@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
{
  finder = "files",
  format = "file",
  hidden = false,
  ignored = false,
  follow = false,
  supports_live = true,
}

`git_files`

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`

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`

---@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`

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

`git_status`

{
  finder = "git_status",
  format = "git_status",
  preview = "git_status",
}

`grep`

---@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 buffers? boolean search in open buffers
---@field need_search? boolean require a search pattern
{
  finder = "grep",
  format = "file",
  live = true, -- live grep by default
  supports_live = true,
}

`grep_buffers`

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

`grep_word`

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

`help`

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`

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

`jumps`

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

`keymaps`

---@class snacks.picker.keymaps.Config: snacks.picker.Config
---@field global? boolean show global keymaps
---@field local? boolean show buffer keymaps
---@field modes? string[]
{
  finder = "vim_keymaps",
  format = "keymap",
  preview = "preview",
  global = true,
  ["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`

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

`loclist`

Loclist

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

`lsp_declarations`

LSP declarations

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

`lsp_definitions`

LSP definitions

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

`lsp_implementations`

LSP implementations

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

`lsp_references`

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

`lsp_symbols`

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
{
  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`

LSP type definitions

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

`man`

{
  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`

---@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`

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

`picker_format`

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

`picker_layouts`

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

`picker_preview`

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

`pickers`

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`

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`

Quickfix list

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

`recent`

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`

Neovim registers

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

`resume`

Special picker that resumes the last picker

{}

`search_history`

Neovim search history

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

`zoxide`

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 = "{source} {live}",
      title_pos = "center",
      { win = "input", height = 1, border = "bottom" },
      { win = "list", border = "none" },
    },
    { win = "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", height = 0.4, border = "rounded" },
    {
      box = "vertical",
      border = "rounded",
      title = "{source} {live}",
      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 = " {source} {live}",
    title_pos = "left",
    { win = "input", height = 1, border = "bottom" },
    {
      box = "horizontal",
      { win = "list", border = "none" },
      { win = "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", 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 = "{source} {live}", title_pos = "center" },
    },
    {
      win = "preview",
      width = 0.45,
      border = "rounded",
      title = " Preview ",
      title_pos = "center",
    },
  },
}

`vertical`

{
  layout = {
    backdrop = false,
    width = 0.5,
    min_width = 80,
    height = 0.8,
    min_height = 30,
    box = "vertical",
    border = "rounded",
    title = "{source} {live}",
    title_pos = "center",
    { win = "input", height = 1, border = "bottom" },
    { win = "list", border = "none" },
    { win = "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 = "{source} {live}", title_pos = "center" },
    { win = "list", border = "hpad" },
    { win = "preview", border = "rounded" },
  },
}

📦 `snacks.picker.actions`

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

`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.edit()`

Snacks.picker.actions.edit(picker)

`Snacks.picker.actions.edit_split()`

Snacks.picker.actions.edit_split(picker)

`Snacks.picker.actions.edit_tab()`

Snacks.picker.actions.edit_tab(picker)

`Snacks.picker.actions.edit_vsplit()`

Snacks.picker.actions.edit_vsplit(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.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.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_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.search()`

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

`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_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 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 source_name string
---@field closed? boolean
---@field hist_idx number
---@field hist_cursor number
---@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

picker:current()

`picker:empty()`

Check if the picker is empty

picker:empty()

`picker:filter()`

Get the active filter

picker:filter()

`picker:find()`

Clear the list and run the finder and matcher

---@param opts? {on_done?: fun()} Callback when done
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 finder items

picker:items()

`picker:iter()`

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

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

`picker:match()`

Run the matcher with the current pattern. May also trigger a new find if the search string has changed, like during live searches.

picker:match()

`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`
picker:selected(opts)

`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:word()`

Get the word under the cursor or the current visual selection

picker:word()

36 KiB Raw Permalink Blame History

🍿 picker

📦 Setup

⚙️ Config

🚀 Examples

general

todo_comments

trouble

📚 Types

📦 Module

Snacks.picker()

Snacks.picker.pick()

Snacks.picker.select()

🔍 Sources

autocmds

buffers

cliphist

colorschemes

command_history

commands

diagnostics

diagnostics_buffer

files

git_files

git_log

git_log_file

git_log_line

git_status

grep

grep_buffers

grep_word

help

highlights

jumps

keymaps

lines

loclist

lsp_declarations

lsp_definitions

lsp_implementations

lsp_references

lsp_symbols

lsp_type_definitions

man

marks

picker_actions

picker_format

picker_layouts

picker_preview

pickers

projects

qflist

recent

registers

resume

search_history

zoxide