# How to Set Up Telescope for Advanced Search and Navigation in jdhao/nvim-config

> Master Telescope for advanced search and navigation in jdhao/nvim-config. Configure and bind pickers for an enhanced Neovim experience. Learn setup steps now.

- Repository: [jdhao/nvim-config](https://github.com/jdhao/nvim-config)
- Tags: how-to-guide
- Published: 2026-03-04

---

**You can set up Telescope for advanced search and navigation by creating a dedicated configuration file at [`lua/config/telescope.lua`](https://github.com/jdhao/nvim-config/blob/main/lua/config/telescope.lua), updating the plugin specification in [`lua/plugin_specs.lua`](https://github.com/jdhao/nvim-config/blob/main/lua/plugin_specs.lua) to require this module, and binding the built-in pickers to intuitive keymaps in [`lua/mappings.lua`](https://github.com/jdhao/nvim-config/blob/main/lua/mappings.lua).**

The **jdhao/nvim-config** repository provides a minimal, performance-oriented Neovim setup where Telescope is lazy-loaded to reduce startup time. Because the plugin is only loaded when you execute the `:Telescope` command, you must explicitly extend the default configuration to unlock advanced fuzzy-finding, file browsing, and symbol navigation capabilities.

## Understanding the Default Telescope Configuration

In [`lua/plugin_specs.lua`](https://github.com/jdhao/nvim-config/blob/main/lua/plugin_specs.lua) (lines 150–162), Telescope is declared with lazy-loading enabled via the `cmd = "Telescope"` trigger. This specification includes `nvim-telescope/telescope-symbols.nvim` as a dependency but does not include a `config` function, meaning the plugin runs with factory defaults until you override them.

```lua
{
  "nvim-telescope/telescope.nvim",
  cmd = "Telescope",
  dependencies = {
    "nvim-telescope/telescope-symbols.nvim",
  },
},

```

This setup defers loading until you invoke any Telescope command, keeping your Neovim startup fast while maintaining access to powerful fuzzy-finding tools.

## Creating a Custom Telescope Configuration File

To override defaults and enable extensions, create [`lua/config/telescope.lua`](https://github.com/jdhao/nvim-config/blob/main/lua/config/telescope.lua) and invoke `require('telescope').setup()` with your preferences. This file customizes the UI, defines ignore patterns, and configures the mappings for insert mode navigation.

```lua
local status_ok, telescope = pcall(require, "telescope")
if not status_ok then return end

telescope.setup{
  defaults = {
    prompt_prefix = "🔍 ",
    selection_caret = "➜ ",
    path_display = { "smart" },
    file_ignore_patterns = { "node_modules", ".git/", "dist/" },
    layout_strategy = "horizontal",
    layout_config = {
      horizontal = { preview_width = 0.55 },
      vertical = { width = 0.9 },
    },
    mappings = {
      i = {
        ["<C-j>"] = require("telescope.actions").move_selection_next,
        ["<C-k>"] = require("telescope.actions").move_selection_previous,
        ["<Esc>"] = require("telescope.actions").close,
      },
    },
  },
  extensions = {
    ["ui-select"] = {
      require("telescope.themes").get_dropdown(),
    },
    symbols = {
      ignore_cases = true,
      symbols = {
        "emoji",
        "math",
        "git",
        "arrow",
        "currency",
        "latin",
        "greek",
        "geometric",
      },
    },
  },
}

-- Load extensions
telescope.load_extension('ui-select')
telescope.load_extension('symbols')

```

Key configuration highlights include:
- **file_ignore_patterns**: Excludes `node_modules`, `.git/`, and build directories from search results
- **layout_strategy**: Uses horizontal splits with a dedicated preview width of 55%
- **mappings**: Binds `<C-j>` and `<C-k>` to navigate results, and `<Esc>` to close the picker in insert mode

## Integrating Your Configuration with lazy.nvim

After creating the configuration file, modify the Telescope entry in [`lua/plugin_specs.lua`](https://github.com/jdhao/nvim-config/blob/main/lua/plugin_specs.lua) to load your custom setup. Add a `config` function that requires the new module, ensuring your settings apply when the plugin loads.

```lua
{
  "nvim-telescope/telescope.nvim",
  cmd = "Telescope",
  dependencies = {
    "nvim-telescope/telescope-symbols.nvim",
  },
  config = function()
    require("config.telescope")   -- Load custom setup
  end,
},

```

This wiring ensures that [`lua/config/telescope.lua`](https://github.com/jdhao/nvim-config/blob/main/lua/config/telescope.lua) executes immediately after Telescope loads, overriding the factory defaults with your advanced search configuration.

## Binding Telescope Commands to Keys

While Telescope provides powerful pickers such as `find_files`, `live_grep`, and `buffers`, you must bind them to keys in [`lua/mappings.lua`](https://github.com/jdhao/nvim-config/blob/main/lua/mappings.lua) (around lines 70–80) for efficient navigation. Use `vim.keymap.set` to create normal-mode shortcuts that trigger specific pickers.

```lua
local keymap = vim.keymap

-- Telescope shortcuts
keymap.set('n', '<leader>ff', '<cmd>Telescope find_files<cr>',   { desc = 'Find file' })
keymap.set('n', '<leader>fg', '<cmd>Telescope live_grep<cr>',    { desc = 'Live grep' })
keymap.set('n', '<leader>fb', '<cmd>Telescope buffers<cr>',      { desc = 'Buffers' })
keymap.set('n', '<leader>fh', '<cmd>Telescope help_tags<cr>',    { desc = 'Help tags' })
keymap.set('n', '<leader>fs', '<cmd>Telescope symbols<cr>',      { desc = 'Symbols picker' })

```

These mappings provide instant access to:
- **find_files**: Fuzzy search for files in the current working directory
- **live_grep**: Real-time grep across project files using ripgrep
- **buffers**: Quickly switch between open buffers
- **symbols**: Insert emoji, math symbols, and special characters via the `telescope-symbols.nvim` extension

## Summary

- **Telescope** in jdhao/nvim-config is lazy-loaded via `cmd = "Telescope"` in [`lua/plugin_specs.lua`](https://github.com/jdhao/nvim-config/blob/main/lua/plugin_specs.lua) to minimize startup overhead.
- Create [`lua/config/telescope.lua`](https://github.com/jdhao/nvim-config/blob/main/lua/config/telescope.lua) to override defaults, set ignore patterns, and configure UI preferences using `require('telescope').setup()`.
- Update the plugin specification to include a `config` function that requires your custom configuration file.
- Add keybindings in [`lua/mappings.lua`](https://github.com/jdhao/nvim-config/blob/main/lua/mappings.lua) to invoke `find_files`, `live_grep`, `buffers`, and the `symbols` extension with leader-key shortcuts.
- Load extensions explicitly with `telescope.load_extension()` to enable advanced pickers like symbols and ui-select.

## Frequently Asked Questions

### Where is Telescope defined in jdhao/nvim-config?

Telescope is declared in [`lua/plugin_specs.lua`](https://github.com/jdhao/nvim-config/blob/main/lua/plugin_specs.lua) between lines 150 and 162. The specification uses the `cmd` key to lazy-load the plugin only when you execute a `:Telescope` command, and it lists `telescope-symbols.nvim` as a dependency for enhanced symbol picking.

### How do I enable the symbols picker in Telescope?

First, ensure `telescope-symbols.nvim` is listed in the dependencies array of your Telescope plugin spec (which it is by default in this repository). Then, add the `symbols` configuration table inside the `extensions` section of your `setup()` call, specifying which symbol categories to include. Finally, run `telescope.load_extension('symbols')` to activate it.

### Why does Telescope take time to open initially?

Because the jdhao/nvim-config repository configures Telescope with `cmd = "Telescope"`, the plugin is not loaded during Neovim startup. The first time you invoke a Telescope command, the plugin manager must load the Lua modules and dependencies, causing a brief delay. Subsequent invocations during the same session will be instantaneous.

### Can I use Telescope without modifying plugin_specs.lua?

You can use Telescope with its factory defaults immediately after installation because the plugin spec already declares it. However, to enable advanced search features, custom keymaps, or extensions like symbols, you must modify [`plugin_specs.lua`](https://github.com/jdhao/nvim-config/blob/main/plugin_specs.lua) to include a `config` function that loads your custom setup file, or place your configuration in a file that loads after the plugin manager initializes.