visual-surround.nvim

Visual surround is a lightweight and flexible Neovim plugin designed to simplify text manipulation using surround elements. Inspired by popular surrounding plugins, it enables users to easily add or remove surrounding characters like parentheses, brackets, quotes, and custom strings. All within a visual selection.

Since this plugin only works in visual mode, by default, all keymaps are one character long. So for example, to surround a selection with parentheses, you would press ( or ) in visual mode and it's done. Of course, the mappings can be customized to your liking.

Note

If you want a more feature-rich plugin, check out nvim-surround or mini.surround, but if you only using these plugins in visual mode, this plugin is for you.

📺 Showcase

visual-surround-showcase.mp4

📋 Installation

lazy:

{
    "NStefan002/visual-surround.nvim",
    config = function()
        require("visual-surround").setup({
            -- your config
        })
        -- [optional] custom keymaps
    end,
}

packer:

use({
    "NStefan002/visual-surround.nvim",
    config = function()
        require("visual-surround").setup({
            -- your config
        })
        -- [optional] custom keymaps
    end,
})

⚙ Configuration

{
    -- if set to false, the user must manually add keymaps
    use_default_keymaps = true,
    -- will be ignored if use_default_keymaps is set to false
    surround_chars = { "{", "}", "[", "]", "(", ")", "'", '"', "`", "<", ">" },
    -- delete surroundings when the selection block starts and ends with surroundings
    enable_wrapped_deletion = false,
    -- whether to exit visual mode after adding surround
    exit_visual_mode = true,
}

Note

< and > only work in visual (v) and visual-block mode (CTRL-V) to avoid conflicts with the default < / > in visual-line mode (V). You can change this by defining a mapping yourself (see Tips).

⚒️ API

This plugin exposes the surround function that should be used in visual mode to surround the selected text. The function receives two parameters:

1. opening (string) -> String that should be placed at the beginning of the selection.
2. [optional] closing (string) -> String that should be placed at the end of the selection. Do not provide this parameter if you want the opening string to be placed at the end as well. (If the opening string is any of the characters from surround_chars, this function will correctly determine closing string.)

👀 Tips

Set some additional keymaps

require("visual-surround").setup({
    use_default_keymaps = true, -- to enable default keymaps
})

vim.keymap.set("v", "sd", function()
    require("visual-surround").surround("<div>", "</div>")
end, { desc = "Wrap selection in a div" })

Also, take a look at this example in my config.

Set new keymaps

require("visual-surround").setup({
    use_default_keymaps = false,
})

local prefix = "s" -- optional, just an idea if you prefer it this way
local surround_chars = { "{", "[", "(", "'", '"', "<" }
local surround = require("visual-surround").surround
for _, key in pairs(surround_chars) do
    vim.keymap.set("v", prefix .. key, function()
        surround(key)
    end, { desc = "[visual-surround] Surround selection with " .. key })
end

Prompt for a custom surround string

vim.keymap.set("v", "ss", function()
    local opening = vim.fn.input("Opening: ")
    local closing = vim.fn.input("Closing: ") -- leave empty if you want to use opening string for both
    require("visual-surround").surround(opening, closing)
end, { desc = "[visual-surround] Surround selection with custom string" })