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.

Contributing

See the contributing file.

Shoutouts

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