Namu configuration

README · Recipes

Namu works with require("namu").setup({}). Override only the options you want to change. With lazy.nvim, use the same table as opts in the plugin specification.

Setup structure

require("namu").setup({
  global = {
    -- Shared picker settings. These are the current defaults.
    display = { format = "tree_guides" },
    jump = { enabled = true, toggle_key = ";", auto_activate = false },
  },
  namu_symbols = { enable = true },
  workspace = { enable = true },
  watchtower = { enable = true },
  diagnostics = { enable = true },
  callhierarchy = { enable = true },
  namu_ctags = { enable = false },
  colorscheme = { enable = false },
  ui_select = { enable = false },
})

The symbols module is named namu_symbols, and the call hierarchy module is named callhierarchy. Options belong directly under a module key. The older module.options nesting is still accepted; new configurations should use the direct form.

How overrides resolve

Shared defaults are merged with module defaults, then your global settings, then your module settings. A module override wins over a global override. Legacy module.options settings are applied before direct module options. Module implementations also supply their own base defaults for options such as symbol icons and filtering.

require("namu").setup({
  global = { window = { max_width = 100 } },
  workspace = { window = { max_width = 75 } },
})

Here, the workspace picker uses a maximum width of 75; other pickers use 100. Lua lists are merged by index, so list overrides should be checked when replacing defaults.

Full defaults

The following files contain the complete defaults, including filetype filters, icons, and module-specific settings. They are the authoritative reference:

• Shared and module defaults
• Symbol defaults
• Picker and jump defaults
• Enabled modules
• Configuration types

For a copyable configuration covering the main settings and every module, see configuration.lua. It is a starting point; it does not duplicate every internal or experimental option from the source files.

To inspect the shared configuration resolved for a module inside Neovim:

:lua require("namu.core.config_manager").debug_config("namu_symbols")

To inspect the symbols configuration after opening its picker:

:lua vim.print(require("namu.namu_symbols").config)

Shared picker options

Place these under global to affect all pickers, or under a module to affect that picker.

Jump labels

Press ;, then a label to select its item. Labels are assigned to visible rows, up to the number of characters in jump.keys. Use distinct single-byte characters. While jump mode is active, label keys select rows instead of typing into the filter. Press ; or <Esc> to return to filtering. Without active jump mode, <Esc> closes the picker.

Movement and actions

Action keymaps live in custom_keymaps. Each action accepts keys (a string or list), a desc, and an optional handler. Availability depends on the module and item data.

For symbols, actions.close_on_yank defaults to false, actions.close_on_delete to true, and actions.close_on_quickfix to false. Integration examples are in action_intergration.md.

Display and current-item marker

The current row's background comes from NamuCurrentItem, independently of the prefix marker. Customize it with a highlight definition, as shown in the highlight recipe.

Window

Modules can override dimensions and title prefixes. row_position supports "center", "top10", "top10_right", "center_right", and "bottom"; symbols default to "top10".

Module options

Symbols (namu_symbols)

Tree-sitter is also accessible directly with :Namu treesitter. Parser and query support determine which symbols can be extracted. A Tree-sitter preference can fall back to LSP when available.

Workspace (workspace)

Uses the language server's workspace symbol support. The default window width is 50–75 columns. :Namu workspace query supplies an initial query.

Open buffers (watchtower)

Collects symbols across open buffers. It defaults to tree guides, preserve_hierarchy = true, and the same Lua test enhancement settings as symbols.

Diagnostics (diagnostics)

Defaults to tree guides, preserve_hierarchy = true, and row_position = "top10". The window defaults to 79–100 columns and at most 15 rows. icons and highlights have Error, Warn, Info, and Hint entries. The code action mapping is <C-CR> / <D-CR> when supported by the terminal and language server.

Calls (callhierarchy)

Requires a language server with call hierarchy support. Defaults:

require("namu").setup({
  callhierarchy = {
    preserve_hierarchy = true,
    sort_by_nesting_depth = true,
    call_hierarchy = {
      max_depth = 2,
      max_depth_limit = 4,
      show_cycles = false,
    },
  },
})

Ctags (namu_ctags)

Disabled by default. Enable it and install Universal Ctags to use :Namu ctags or :Namu ctags watchtower.

Colorschemes (colorscheme)

Disabled by default. Enable it to use the colorscheme picker and its setup behavior. See the optional picker recipe.

UI selection (ui_select)

Disabled by default. Enabling it replaces vim.ui.select. It uses raw display, numbered items, and a maximum height of 30 rows. Shared jump settings apply here too; use a ui_select.jump override to change them for selection dialogs.

Highlights

Namu defines its highlights in core/highlights.lua.

The default focused-row background uses CursorLine when it provides enough contrast. Otherwise, Namu tries PmenuSel, Visual, and a derived contrasting background. Transparent pickers prefer selection colors. Defaults refresh on colorscheme changes, while explicit current-item and icon highlight definitions take precedence. A custom override is responsible for its own contrast.

See recipes for working examples.