Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/chrisgrieser/nvim-various-textobjs/llms.txt

Use this file to discover all available pages before exploring further.

The .setup() call is entirely optional — if you are wiring up keymaps manually and are happy with all the defaults, you do not need to call it at all. You only need setup() if you want to enable the built-in default keymaps, disable a subset of them, or change any of the options documented below.

​
Default Configuration

The block below shows the full default configuration with all available options and their default values. Pass only the keys you want to override — the setup call performs a deep merge so omitted keys retain their defaults. 
require("various-textobjs").setup {
  keymaps = {
    useDefaults = false,
    ---@type string[]
    disabledDefaults = {},
  },
  forwardLooking = {
    small = 5,
    big = 15,
  },
  behavior = {
    jumplist = true,
  },
  textobjs = {
    indentation = {
      blanksAreDelimiter = false,
    },
    subword = {
      noCamelToPascalCase = true,
    },
    diagnostic = {
      wrap = true,
    },
    url = {
      patterns = { [[%l%l%l+://[^%s)%]}"'`>]+]] },
    },
  },
  notify = {
    icon = "󰠱",
    whenObjectNotFound = true,
  },
  debug = false,
}

​
Option Reference

​
keymaps

​
keymaps.useDefaults
boolean
default:"false"
When true, registers all default keymaps from the built-in keymap table on plugin load. If lazy-loading the plugin via keys = {}, set lazy = false instead — default keymaps cannot be registered when the plugin loads from a key event.
​
keymaps.disabledDefaults
string[]
default:"{}"
List of keymap strings to exclude when useDefaults = true. For example: { "ai", "!" } disables the ai indentation and ! diagnostic keymaps while keeping every other default keymap active.

​
forwardLooking

​
forwardLooking.small
integer
default:"5"
Lines to search forward for text objects assigned the “small” seek distance. Applies to: anyBracket, anyQuote, toNextClosingBracket, toNextQuotationMark, lineCharacterwise, value, key, number, chainMember, argument, color, doubleSquareBrackets, subword, emoji.
​
forwardLooking.big
integer
default:"15"
Lines to search forward for text objects assigned the “big” seek distance. Applies to: url, filepath, closedFold.

​
behavior

​
behavior.jumplist
boolean
default:"true"
When true, the cursor position before a text object selection is saved to the jumplist, so <C-o> can return to the position you were at before the operation.

​
textobjs (per-object settings)

​
textobjs.indentation.blanksAreDelimiter
boolean
default:"false"
Controls how blank lines interact with the indentation text object. When false, blank lines within an indented block are included — the block expands through them. When true, blank lines act as delimiters and split the indentation block, which is useful if you prefer a tighter selection that stops at empty lines.
​
textobjs.subword.noCamelToPascalCase
boolean
default:"true"
When true and you delete the first subword of a camelCase word, the plugin automatically lowercases the following subword so the result stays camelCase rather than accidentally becoming PascalCase. For example, deleting my from myVariable produces variable rather than Variable.
​
textobjs.diagnostic.wrap
boolean
default:"true"
When true, the diagnostic text object wraps around to the start of the buffer if no next diagnostic is found after the cursor position, ensuring you can always reach a diagnostic regardless of cursor location.
​
textobjs.url.patterns
string[]
Lua pattern list used to detect URLs. The default pattern matches any protocol://... URL (three or more lowercase letters followed by :// and non-whitespace, non-delimiter characters). Override this list to restrict matching to specific protocols — for example, { [[https?://[^%s)%]}"' + “" + >]+]] }` matches only HTTP and HTTPS URLs.

​
notify

​
notify.icon
string
default:"󰠱"
Icon shown alongside the notification message in plugins like nvim-notify when a text object cannot be found. Has no effect if you are not using a notification plugin.
​
notify.whenObjectNotFound
boolean
default:"true"
When true, displays a notification whenever a text object search comes up empty — i.e., no match was found within the forward-looking range. Set to false to suppress these messages and fail silently.

​
debug

​
debug
boolean
default:"false"
Enables internal diagnostic messages during text object operations. Useful when developing custom text object integrations or debugging unexpected selection behavior.

​
Dynamically Switching Settings

Because setup() deep-merges with the existing config (using vim.tbl_deep_extend("force", ...)), you can call it multiple times at runtime — including inside a keymap function — to temporarily override specific settings for a single text object invocation. This is the recommended pattern for creating two keymaps that select the same text object type but with different matching behavior. A common example is having separate keymaps for HTTP and FTP URLs: 
vim.keymap.set({ "o", "x" }, "H", function()
  require("various-textobjs").setup {
    textobjs = {
      url = {
        patterns = { [[https?://[^%s)%]}"'`>]+]] },
      },
    },
  }
  return "<cmd>lua require('various-textobjs').url()<CR>"
end, { expr = true, desc = "http-url textobj" })

vim.keymap.set({ "o", "x" }, "F", function()
  require("various-textobjs").setup {
    textobjs = {
      url = {
        patterns = { [[ftp://[^%s)%]}"'`>]+]] },
      },
    },
  }
  return "<cmd>lua require('various-textobjs').url()<CR>"
end, { expr = true, desc = "ftp-url textobj" })
Each keymap is set with expr = true so the function return value (the Ex command string) is executed as the keymap RHS, which preserves dot-repeat. The setup() call runs first and narrows the URL pattern to the desired protocol only; the subsequent url() call then uses that updated pattern.
Each setup() call deep-merges with the existing config, so you only need to specify the keys you want to change. All other options remain at their current values — either the defaults or whatever you set during plugin initialization.

Build docs developers (and LLMs) love

Get started for freeTalk to us