🍿 snacks.nvim

A collection of small QoL plugins for Neovim.

✨ Features

<!-- toc:start -->

| Snack | Description | Setup | | ----- | ----------- | :---: | | animate | Efficient animations including over 45 easing functions (library) | | | bigfile | Deal with big files | ‼️ | | bufdelete | Delete buffers without disrupting window layout | | | dashboard | Beautiful declarative dashboards | ‼️ | | debug | Pretty inspect & backtraces for debugging | | | dim | Focus on the active scope by dimming the rest | | | explorer | A file explorer (picker in disguise) | ‼️ | | gh | GitHub CLI integration | | | git | Git utilities | | | gitbrowse | Open the current file, branch, commit, or repo in a browser (e.g. GitHub, GitLab, Bitbucket) | | | image | Image viewer using Kitty Graphics Protocol, supported by kitty, wezterm and ghostty | ‼️ | | indent | Indent guides and scopes | | | input | Better vim.ui.input | ‼️ | | keymap | Better vim.keymap with support for filetypes and LSP clients | | | layout | Window layouts | | | lazygit | Open LazyGit in a float, auto-configure colorscheme and integration with Neovim | | | notifier | Pretty vim.notify | ‼️ | | notify | Utility functions to work with Neovim's vim.notify | | | picker | Picker for selecting items | ‼️ | | profiler | Neovim lua profiler | | | quickfile | When doing nvim somefile.txt, it will render the file as quickly as possible, before loading your plugins. | ‼️ | | rename | LSP-integrated file renaming with support for plugins like neo-tree.nvim and mini.files. | | | scope | Scope detection, text objects and jumping based on treesitter or indent | ‼️ | | scratch | Scratch buffers with a persistent file | | | scroll | Smooth scrolling | ‼️ | | statuscolumn | Pretty status column | ‼️ | | terminal | Create and toggle floating/split terminals | | | toggle | Toggle keymaps integrated with which-key icons / colors | | | util | Utility functions for Snacks (library) | | | win | Create and manage floating windows or splits | | | words | Auto-show LSP references and quickly navigate between them | ‼️ | | zen | Zen mode • distraction-free coding | |

<!-- toc:end -->

⚡️ Requirements

• Neovim >= 0.9.4
• for proper icons support:
  • mini.icons (optional)
  • nvim-web-devicons (optional)
  • a Nerd Font (optional)

📦 Installation

Install the plugin with your package manager:

lazy.nvim

[!important] A couple of plugins require snacks.nvim to be set-up early. Setup creates some autocmds and does not load any plugins. Check the code to see what it does.

[!caution] You need to explicitly pass options for a plugin or set enabled = true to enable it.

[!tip] It's a good idea to run :checkhealth snacks to see if everything is set up correctly.

{
  "folke/snacks.nvim",
  priority = 1000,
  lazy = false,
  ---@type snacks.Config
  opts = {
    -- your configuration comes here
    -- or leave it empty to use the default settings
    -- refer to the configuration section below
    bigfile = { enabled = true },
    dashboard = { enabled = true },
    explorer = { enabled = true },
    indent = { enabled = true },
    input = { enabled = true },
    picker = { enabled = true },
    notifier = { enabled = true },
    quickfile = { enabled = true },
    scope = { enabled = true },
    scroll = { enabled = true },
    statuscolumn = { enabled = true },
    words = { enabled = true },
  },
}

For an in-depth setup of snacks.nvim with lazy.nvim, check the example below.

⚙️ Configuration

Please refer to the readme of each plugin for their specific configuration.

<details><summary>Default Options</summary> <!-- config:start -->

---@class snacks.Config
---@field animate? snacks.animate.Config
---@field bigfile? snacks.bigfile.Config
---@field dashboard? snacks.dashboard.Config
---@field dim? snacks.dim.Config
---@field explorer? snacks.explorer.Config
---@field gh? snacks.gh.Config
---@field gitbrowse? snacks.gitbrowse.Config
---@field image? snacks.image.Config
---@field indent? snacks.indent.Config
---@field input? snacks.input.Config
---@field layout? snacks.layout.Config
---@field lazygit? snacks.lazygit.Config
---@field notifier? snacks.notifier.Config
---@field picker? snacks.picker.Config
---@field profiler? snacks.profiler.Config
---@field quickfile? snacks.quickfile.Config
---@field scope? snacks.scope.Config
---@field scratch? snacks.scratch.Config
---@field scroll? snacks.scroll.Config
---@field statuscolumn? snacks.statuscolumn.Config
---@field terminal? snacks.terminal.Config
---@field toggle? snacks.toggle.Config
---@field win? snacks.win.Config
---@field words? snacks.words.Config
---@field zen? snacks.zen.Config
---@field styles? table<string, snacks.win.Config>
---@field image? snacks.image.Config|{}
{
  image = {
    -- define these here, so that we don't need to load the image module
    formats = {
      "png",
      "jpg",
      "jpeg",
      "gif",
      "bmp",
      "webp",
      "tiff",
      "heic",
      "avif",
      "mp4",
      "mov",
      "avi",
      "mkv",
      "webm",
      "pdf",
      "icns",
    },
  },
}

<!-- config:end --> </details>

Some plugins have examples in their documentation. You can include them in your config like this:

{
  dashboard = { example = "github" }
}

If you want to customize options for a plugin after they have been resolved, you can use the config function:

{
  gitbrowse = {
    config = function(opts, defaults)
      table.insert(opts.remote_patterns, { "my", "custom pattern" })
    end
  },
}

🚀 Usage

See the example below for how to configure snacks.nvim.

<!-- example:start -->

{
  "folke/snacks.nvim",
  priority = 1000,
  lazy = false,
  ---@type snacks.Config
  opts = {
    bigfile = { enabled = true },
    dashboard = { enabled = true },
    explorer = { enabled = true },
    indent = { enabled = true },
    input = { enabled = true },
    notifier = {
      enabled = true,
      timeout = 3000,
    },
    picker = { enabled = true },
    quickfile = { enabled = true },
    scope = { enabled = true },
    scroll = { enabled = true },
    statuscolumn = { enabled = true },
    words = { enabled = true },
    styles = {
      notification = {
        -- wo = { wrap = true } -- Wrap notifications
      }
    }
  },
  keys = {
    -- Top Pickers & Explorer
    { "<leader><space>", function() Snacks.picker.smart() end, desc = "Smart Find Files" },
    { "<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>n", function() Snacks.picker.notifications() end, desc = "Notification History" },
    { "<leader>e", function() Snacks.explorer() end, desc = "File Explorer" },
    -- 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>fp", function() Snacks.picker.projects() end, desc = "Projects" },
    { "<leader>fr", function() Snacks.picker.recent() end, desc = "Recent" },
    -- git
    { "<leader