nvim-surround

Surround selections, stylishly 😎

README_demo_3.mp4

✨ Features

Add/change/remove surrounding pairs and HTML tags
- Change only the surrounding HTML tag's element type, and leave its attributes
Dot-repeat previous actions
Set buffer-local mappings and surrounds
Surround using powerful pairs that depend on user input
Jump to the nearest surrounding pair for modification
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
Highlight the section that you are about to surround, as a visual indicator

For more information, see :h nvim-surround.

📦 Installation

packer.nvim

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

🚀 Usage

Information on how to use this plugin can be found in the wiki.

⚙️ Configuration

The Basics

All delimiter keys should be one character exactly, and unique. In the delimiters table, each value is either a pair of strings, representing the left and right surrounding pair, or a function returning a pair of strings. Multi-line strings are represented by tables of strings, with each string representing a new line.

Looking for inspiration/examples? Want to share some cool surrounds that you've made? You can visit the surrounds showcase to see a community-made list of custom surrounds!

Modifying Defaults

To change a preset, give the corresponding key a new value. To disable any functionality, simply set the corresponding key's value to false. For example,

require("nvim-surround").setup({
    delimiters = {
        pairs = { -- Remaps "a" and "b"
            ["a"] = {
                { "this", "has", "several", "lines" },
                "single line",
            },
            ["b"] = function()
                return {
                    "hello",
                    "world",
                }
            end,
        },
        HTML = { -- Disables HTML-style mappings
            ["t"] = false,
            ["T"] = false,
        },
    },
    highlight_motion = { -- Disables highlights
        duration = false,
    },
})

For buffer-local configurations, just call require("nvim-surround").buffer_setup for any buffer that you would like to configure. This can be especially useful for setting filetype-specific surrounds by calling buffer_setup inside ftplugin/[filetype].lua.

For more information, see :h nvim-surround, or the default configuration below.

Default Configuration

require("nvim-surround").setup({
    keymaps = { -- vim-surround style keymaps
        insert = "ys",
        insert_line = "yss",
        visual = "S",
        delete = "ds",
        change = "cs",
    },
    delimiters = {
        invalid_key_behavior = function()
            vim.api.nvim_err_writeln(
                "Error: Invalid character! Configure this message in " ..
                'require("nvim-surround").setup()'
            )
        end,
        pairs = {
            ["("] = { "( ", " )" },
            [")"] = { "(", ")" },
            ["{"] = { "{ ", " }" },
            ["}"] = { "{", "}" },
            ["<"] = { "< ", " >" },
            [">"] = { "<", ">" },
            ["["] = { "[ ", " ]" },
            ["]"] = { "[", "]" },
            -- Define pairs based on function evaluations!
            ["i"] = function()
                return {
                    require("nvim-surround.utils").get_input(
                        "Enter the left delimiter: "
                    ),
                    require("nvim-surround.utils").get_input(
                        "Enter the right delimiter: "
                    )
                }
            end,
            ["f"] = function()
                return {
                    require("nvim-surround.utils").get_input(
                        "Enter the function name: "
                    ) .. "(",
                    ")"
                }
            end,
        },
        separators = {
            ["'"] = { "'", "'" },
            ['"'] = { '"', '"' },
            ["`"] = { "`", "`" },
        },
        HTML = {
            ["t"] = "type", -- Change just the tag type
            ["T"] = "whole", -- Change the whole tag contents
        },
        aliases = {
            ["a"] = ">", -- Single character aliases apply everywhere
            ["b"] = ")",
            ["B"] = "}",
            ["r"] = "]",
            -- Table aliases only apply for changes/deletions
            ["q"] = { '"', "'", "`" }, -- Any quote character
            ["s"] = { ")", "]", "}", ">", "'", '"', "`" }, -- Any surrounding delimiter
        },
    },
    highlight_motion = { -- Highlight before inserting/changing surrounds
        duration = 0,
    },
    move_cursor = "begin", -- Move the cursor to the beginning of the surround, or keep it stationary
})

Contributing

See the contributing file.

Shoutouts

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

rafamadriz / nvim-surround