Creating a Custom Command Bar in Neovim
Command bars are a useful addition to many applications that let you search for and execute commands. Neovim's Telescope plugin provides the pieces to create your own with just a bit of Lua programming.
Telescope can be installed using any Neovim plugin manager, and then you're ready to dive in. Even if you haven't used Lua before, this is fairly straightforward.
First, we'll start by importing some modules.
local telescope = require
local pickers = require
local finders = require
The main modules to be aware of here are
finders. A picker is the actual Telescope window that pops up, and the finder provides the items to show in the picker.
Defining the Commands
Next, we'll define our commands. This may look a bit weird if you're not used to Lua, but objects and arrays are sort of the same thing here, so they both use braces. Lua calls them both "tables."
The actual structure of the commands can look however you want, since you'll convert them to the format that Telescope uses later. Here I have a name, a category, and a function to run when the command is selected, but you can add additional information or functions if you want.
local commands =
Note that just using
CocAction will cause the command to be run to completion before the picker closes. This can cause issues with certain commands and so
CocActionAsync works much better.
The picker in the screenshot above has two columns: the command's name and category. We can use the
entry_display module to help with this formatting. It does not autosize columns though, so first we need to find our column widths.
This code snippet figures out the longest command name. (The
# operator returns the length of a string.)
local longest_command_name = 0
for _, command in ipairs
Next, we can create our formatter.
local entry_display = require
local displayer = entry_display.
With your commands set up, you can create a finder to hold the items. Telescope's finders support a lot of functionality, but here we just have a fixed set of commands in a table. The
finders.new_table method creates a simple finder that can populate its results from this table.
local finder = finders.
entry_maker function above returns information for the picker to use.
valuecan be any arbitrary data. In this case we just use the
displayis a function that formats the item. We use our
displayerfrom above to format the name and the category, with a highlight group applied to the category.
ordinalis the input to the picker's sorting algorithm. Here we're just sorting by name.
Showing the Window
Now we're ready to actually show our picker.
local showCommandBar =
Here we use the default sorter from the Telescope configuration. The
attach_mappings argument lets us add special actions into the picker, and we add one action so that the Enter key will close the picker, get the selected item, and run its action.
Finally, we created a key mapping that would run the function. And that's it!
We covered just the basics here, but there's a lot of opportunity for more advanced functionality.
By moving more of this code inside the
showCommandBar function, you could customize the commands based on aspects of the current buffer, such as showing certain commands only for certain file types.
My current full implementation of this technique can be found on Github.
If you build any other cool functionality around this, I'd love to hear it!