Focus on what matters

unclutter.nvim is a tabline that removes the clutter to help you focus on the files that matter to you.

• Installation
  • Lazy.nvim
  • Packer.nvim
• Features
  • Only show the buffers you need
  • 🔭 Telescope integration
• Customization
  • Utils
• Inspiration

Use your favorite package manager. Don't forget to call setup.

{
  "pablopunk/unclutter.nvim",
  dependencies = {
    "nvim-tree/nvim-web-devicons"   -- optional, to show icons on tabs
    "nvim-telescope/telescope.nvim" -- optional, to use the telescope integration
  },
  config = true -- this will call require("unclutter").setup()
}

You're working on a large project and you're jumping through function definitions and index files that endup cluttering your tabline. Unclutter.nvim will:

A minimal tabline with icons will show:

• Buffers you made changes to.
• Buffers visible in any split.
• Buffers that were open on startup (neovim arguments, restored sessions...).
• Buffers that are not files (file tree, quickfix, help, terminal...).
• Buffers that are marked manually (read below).

Every other buffer will be closed at the time you leave it (BufLeave).

If you use telescope.nvim, you can use it to list all your unclutter.nvim in a floating window:

require('unclutter.telescope').open()

Of course, you can map it to whatever you want:

vim.keymap.set("n", "<leader>b", require("unclutter.telescope").open, { noremap = true })

You can customize the format of the telescope results:

unclutter.telescope { format = "compact" } -- DEFAULT: folder/file.js
unclutter.telescope { format = "cwd" } -- path/folder/file.js
unclutter.telescope { format = "filename" } -- file.js

You can also hide the current buffer in the list:

unclutter.telescope { hide_current = true } -- default: false

If you want to use the telescope integration without the tabline, you can disable it:

require('unclutter').setup {
  tabline = false,
}

Here's the default configuration:

require('unclutter').setup {
  clean_after = 3, -- number of tabs to start uncluttering. i.e don't hide until 4 tabs are open
  tabline = true, -- show tabline. You can set it to false and only use the [telescope integration](#telescopenvim-integration)
}

If you want to hack it or create your own mappings, you can use the following functions:

local unclutter = require("unclutter")
local tabline = require("unclutter.tabline")
local buffer = require("unclutter.buffer")
local plugin = require("unclutter.plugin")

tabline.keep_buffer(bufnr)          -- Show buffer in tabline
tabline.remove_buffer(bufnr)        -- Show buffer in tabline
tabline.toggle_buffer(bufnr)        -- Toggle buffer in tabline
tabline.list()                      -- List tabline buffers

-- If you want to get the current buffer you can use:
local bufnr = buffer.current()
tabline.keep(bufnr)

-- navigate tabline buffers (like :bnext and :bprev)
tabline.next()                      -- Go to next buffer
tabline.prev()                      -- Go to previous buffer

-- handle plugin (on/off)
plugin.enable()                     -- Enable unclutter
plugin.disable()                    -- Disable unclutter

Example mappings:

vim.keymap.set("n", "gn", unclutter.next, { noremap = true })
vim.keymap.set("n", "gp", unclutter.prev, { noremap = true })

I personally have a map to save a file to disk (<c-s> will :w) so the buffer will be kept in the tabline whenever I do <c-s>.

Of course:

:help unclutter

This behavior was inspired by vscode (sorry), that won't keep your tabs open until you hit save (or double-click the tab).

To create the tabline I used mini.tabline as a starting point. It's a great plugin and the one I was using before. The label/tabs implementation on tabline.lua is an adaptation of mini.tabline's code.

Also this plugin was not only inspired by harpoon too, it's the main reason behind it. I was trying to hack harpoon to get this behavior, but didn't like the outcome. The plugin is great but I don't like their tabs implementation and other small stuff. It was there when I realized I could just code my own.

Other plugins I've used to unclutter in the past:

• nvim-early-retirement
• hbac.nvim