Telescope.nvim is less a fuzzy finder and more a dynamic introspection engine for your Neovim instance.
Let’s see it in action. Imagine you’re in a large project and need to find a specific function or configuration file.
-- In your init.lua or a dedicated plugin config file
require('telescope').setup {
defaults = {
mappings = {
i = {
["<C-u>"] = false, -- Disable default scroll up
["<C-d>"] = false, -- Disable default scroll down
},
},
layout_config = {
prompt_position = "top",
results_height = 0.8,
preview_height = 0.5,
},
sorting_strategy = "ascending",
winblend = 0, -- Fully opaque window
}
}
-- Example keybinds
vim.keymap.set('n', '<leader>ff', require('telescope.builtin').find_files, {})
vim.keymap.set('n', '<leader>fg', require('telescope.builtin').live_grep, {})
vim.keymap.set('n', '<leader>fb', require('telescope.builtin').buffers, {})
vim.keymap.set('n', '<leader>fh', require('telescope.builtin').help_tags, {})
With these mappings, hitting <leader>ff (assuming your leader key is \) will open a Telescope prompt at the top of your screen, allowing you to type and filter through all files in your current working directory. <leader>fg does the same but searches the content of your files. <leader>fb lists open buffers, and <leader>fh lets you fuzzy find Neovim help tags.
Telescope’s core strength lies in its extensibility and its ability to leverage Lua for defining new "finders." A finder is essentially a function that produces a list of items (lines of text, file paths, buffer numbers, etc.) that Telescope then displays and allows you to filter. It’s not just about finding files; it’s about finding anything within your Neovim environment. You can create finders for Git branches, recent files, LSP code actions, project-specific tasks, and much more. The builtin module provides a set of common finders, but the real power comes from defining your own.
The setup function is where you configure Telescope’s global behavior. defaults allows you to set common options for all finders. mappings lets you redefine how you interact with the prompt and results; notice here we’ve disabled default scroll behavior to make way for custom ones if needed. layout_config controls the visual appearance of the Telescope window, including where the prompt sits and how much vertical space is allocated to results and the preview pane. sorting_strategy dictates how results are ordered, and winblend controls transparency.
When you trigger a finder, Telescope spawns a new floating window (or a split, depending on configuration) and a prompt. As you type, Telescope doesn’t just filter a static list; it actively re-queries your data source. For live_grep, it’s running rg (ripgrep) or grep in the background. For find_files, it’s using fd or find. The speed comes from these highly optimized external tools and Telescope’s efficient Lua integration. The preview window, by default, shows the content of the selected file or a relevant snippet, offering context without leaving the prompt.
The underlying mechanism for most finders involves a picker. A picker defines how Telescope displays and interacts with a set of results. The builtin finders are pre-configured pickers. When you write your own finder, you’re essentially defining a Lua function that returns a list of strings or Lua tables, which Telescope then hands off to a picker to render. You can customize the picker’s appearance, add custom actions, and even modify how results are displayed. The telescope.actions module provides a rich set of functions for manipulating selections, opening files, and interacting with Neovim.
The true power of Telescope is its ability to integrate with other Neovim plugins. For instance, you can have a Telescope finder that lists all available LSP diagnostics in your project, and selecting one will jump you directly to that location. Or, you could create a finder that lists your project’s tasks defined in a Makefile or Taskfile.yml, allowing you to execute them directly from the Telescope prompt. This creates a unified interface for interacting with various aspects of your development environment, all through fuzzy finding.
When you define a custom finder, it often involves a Lua function that returns a table. This table typically contains a results field, which is a list of items, and potentially other metadata like initial_prompt or selection. Telescope then takes these results and uses a configured picker to display them. The magic is that Telescope can handle different types of results, from simple strings to more complex Lua tables that include display attributes, actions, and custom preview content, making your finders as sophisticated as you need them to be.
The next step in mastering Telescope is exploring custom pickers and integrating them with your workflow.