nvim-surround

Surround selections, stylishly 😎

Warning: This plugin is still in early development, so some things might not be fully fleshed out or stable. Feel free to open an issue or pull request!

nvim_surround_demo_1.mp4

✨ Features

• Surround text objects/visual selections with delimiter pairs
• Delete/Change surrounding delimiters
• Quickly add/change/remove surrounding HTML tags
  • Change only the surrounding HTML tag's element type, and leave its attributes
• Use a single character as an alias for several text-objects
  • E.g. q is aliased to `,',", so csqb replaces the nearest set of quotes with parentheses

📦 Installation

Install this plugin with your favorite package manager:

packer.nvim

-- Lua
use({
    "kylechui/nvim-surround",
    config = function()
        require("nvim-surround").setup({
            -- Configuration here, or leave empty to use defaults
        })
    end
})

vim-plug

" Vim Script
Plug "kylechui/nvim-surround"

lua << EOF
    require("nvim-surround").setup({
        -- Configuration here, or leave empty to use defaults
    })
EOF

⚙️ Configuration

The default configuration is as follows:

require("nvim-surround").setup({
    keymaps = { -- vim-surround style keymaps
        insert = "ys",
        visual = "S",
        delete = "ds",
        change = "cs",
    },
    delimiters = {
        pairs = {
            ["("] = { "( ", " )" },
            [")"] = { "(", ")" },
            ["{"] = { "{ ", " }" },
            ["}"] = { "{", "}" },
            ["<"] = { "< ", " >" },
            [">"] = { "<", ">" },
            ["["] = { "[ ", " ]" },
            ["]"] = { "[", "]" },
        },
        separators = {
            ["'"] = { "'", "'" },
            ['"'] = { '"', '"' },
            ["`"] = { "`", "`" },
        },
        HTML = {
            ["t"] = true, -- Use "t" for HTML-style mappings
        },
        aliases = {
            ["a"] = ">", -- Single character aliases apply everywhere
            ["b"] = ")",
            ["B"] = "}",
            ["r"] = "]",
            ["q"] = { '"', "'", "`" }, -- Table aliases only apply for changes/deletions
        },
    }
})

All keys should be one character exactly. To overwrite any functionality, you only need to specify the keys that you wish to modify. To disable any functionality, simply set the corresponding key's value to false. For example,

require("nvim-surround").setup({
    delimiters = {
        pairs = {
            ["b"] = { "{", "}" },
        },
        HTML = { -- Disables HTML-style mappings
            ["t"] = false,
        },
    },
})

✅ TODO

• Find a better way to use operatorfunc
  • There's probably a better way to avoid the va" white space situation
• Implement dot repeating for modifying surrounds

Shoutouts

• vim-surround
• mini.surround
• Like this project? Give it a ⭐ to show your support!