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.

nvim-various-textobjs supports two approaches to keybindings. You can enable the full default set by passing useDefaults = true in your setup() call and optionally suppressing individual mappings with disabledDefaults. Or you can skip the defaults entirely and define every binding yourself, giving you complete control over which keys are used and how inner and outer variants are split. This page covers both approaches in detail.

​
How keymaps work

Text object keymaps are registered in two modes simultaneously:
  • o (operator-pending) — activated after an operator like d, c, or y. For example, dii deletes the inner indented block.
  • x (visual) — activated from visual mode to extend or shrink the current selection to the text object’s boundaries.
For dot-repeat to work correctly, the keymap’s RHS must be an Ex command string — not a Lua function closure. Neovim replays dot-repeat by re-issuing the last Ex command; if the RHS is a function, there is nothing for Neovim to replay. 
-- CORRECT: dot-repeat works
vim.keymap.set({ "o", "x" }, "U", '<cmd>lua require("various-textobjs").url()<CR>')

-- INCORRECT: dot-repeat does NOT work
vim.keymap.set({ "o", "x" }, "U", function()
  require("various-textobjs").url()
end)
Always use the Ex command form '<cmd>lua require("various-textobjs").TEXTOBJ()<CR>' as the RHS for text object keymaps. Passing a function() ... end closure as the RHS breaks dot-repeat, because Neovim has no Ex command to re-execute when you press ..

​
Simple objects (no parameters)

For text objects that take no arguments, the Ex command string is straightforward. For objects that take a scope argument, create two mappings — one for "inner" and one for "outer" — following the standard i/a prefix convention. 
-- no-parameter object
vim.keymap.set({ "o", "x" }, "U", '<cmd>lua require("various-textobjs").url()<CR>')

-- inner/outer variants
vim.keymap.set({ "o", "x" }, "iS", '<cmd>lua require("various-textobjs").subword("inner")<CR>')
vim.keymap.set({ "o", "x" }, "aS", '<cmd>lua require("various-textobjs").subword("outer")<CR>')

​
Indentation text object (two parameters)

The indentation text object is unique: it takes two separate border parameters rather than a single scope. The first parameter controls whether the line above the indented block is included; the second controls the line below. This lets you mix inner and outer independently for the top and bottom borders. 
vim.keymap.set(
  { "o", "x" },
  "ii",
  '<cmd>lua require("various-textobjs").indentation("inner", "inner")<CR>'
)
vim.keymap.set(
  { "o", "x" },
  "iI",
  '<cmd>lua require("various-textobjs").indentation("inner", "inner")<CR>'
)
vim.keymap.set(
  { "o", "x" },
  "ai",
  '<cmd>lua require("various-textobjs").indentation("outer", "inner")<CR>'
)
vim.keymap.set(
  { "o", "x" },
  "aI",
  '<cmd>lua require("various-textobjs").indentation("outer", "outer")<CR>'
)
The default mappings include both ii and iI for inner-inner indentation, matching the behaviour of vim-indent-object.

​
Column text object (direction parameter)

The column text object takes a direction instead of a scope. The three valid values are "down" (default), "up", and "both". 
vim.keymap.set({ "o", "x" }, "|", '<cmd>lua require("various-textobjs").column("down")<CR>')
vim.keymap.set({ "o", "x" }, "a|", '<cmd>lua require("various-textobjs").column("both")<CR>')

​
Default keymap table

When useDefaults = true is set, the following keymaps are registered automatically. The Inner and Outer columns show the keys for inner and outer variants respectively. Single shows the key used for text objects that have no inner/outer distinction.
Text ObjectInnerOuterSingle
indentationii, iIai, aI—
greedyOuterIndentationigag—
subwordiSaS—
anyBracketioao—
anyQuoteiqaq—
valueivav—
keyikak—
numberinan—
chainMemberimam—
lineCharacterwisei_a_—
closedFoldizaz—
notebookCelliNaN—
filepathiFaF—
colori#a#—
doubleSquareBracketsiDaD—
argumenti,a,—
restOfIndentation——R
nearEoL——n
toNextClosingBracket——C
toNextQuotationMark——Q
restOfParagraph——r
entireBuffer——gG
visibleInWindow——gw
restOfWindow——gW
diagnostic——!
column——|
url——L
lastChange——g;
emoji——.

​
Disabling specific defaults

If you want most defaults but need to reclaim a handful of keys for other purposes, use disabledDefaults to suppress individual mappings by key. The rest of the defaults remain active. 
require("various-textobjs").setup {
  keymaps = {
    useDefaults = true,
    disabledDefaults = { "ai", "!" }, -- disable only 'ai' and '!'
  },
}
If you lazy-load this plugin (e.g. with event = "VeryLazy" in lazy.nvim), the default keymaps cannot be registered at startup. To use useDefaults = true with lazy.nvim you must also set lazy = false in your plugin spec so the plugin loads unconditionally on startup.

Build docs developers (and LLMs) love

Get started for freeTalk to us