nvim-surround

Surround selections, stylishly

✨ Features

• Add/delete/change surrounding pairs
  • Function calls and HTML tags out-of-the-box
• Dot-repeat previous actions
• Set buffer-local mappings and surrounds
• 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
• Surround using powerful pairs that depend on user input
• Modify custom surrounds
  • First-class support for Vim motions, Lua patterns, and Tree-sitter nodes
• Highlight selections for visual feedback

🔒 Requirements

• Neovim 0.8+
• [Recommended] If nvim-treesitter-textobjects is installed, then Tree-sitter text-objects can be used to define surrounds, simplifying configuration

📦 Installation

Install this plugin using your favorite plugin manager, and then call require("nvim-surround").setup().

lazy.nvim

{
    "kylechui/nvim-surround",
    version = "^3.0.0", -- Use for stability; omit to use `main` branch for the latest features
    event = "VeryLazy",
    config = function()
        require("nvim-surround").setup({
            -- Configuration here, or leave empty to use defaults
        })
    end
}

packer.nvim

use({
    "kylechui/nvim-surround",
    tag = "*", -- Use for stability; omit to use `main` branch for the latest features
    config = function()
        require("nvim-surround").setup({
            -- Configuration here, or leave empty to use defaults
        })
    end
})

🚀 Usage

The three “core” operations of add/delete/change can be done with the keymaps ys{motion}{char}, ds{char}, and cs{target}{replacement}, respectively. For the following examples, * will denote the cursor position:

    Old text                    Command         New text
--------------------------------------------------------------------------------
    surr*ound_words             ysiw)           (surround_words)
    surr*ound_words             ysiw(           ( surround_words )
    *make strings               ys
quot;            "make strings"
    [delete ar*ound me!]        ds]             delete around me!
    remove <b>HTML t*ags</b>    dst             remove HTML tags
    'change quot*es'            cs'"            "change quotes"
    <b>or tag* types</b>        csth1<CR>       <h1>or tag types</h1>
    delete(functi*on calls)     dsf             function calls

Note that surrounding with an opening delimiter (e.g. () will add a space before/after the selection, while surrounding with the closing delimiter (e.g. )) will not include the spaces. Detailed information on how to use this plugin can be found in :h nvim-surround.usage.

:gear: Configuration

The default configuration is found here. Simply call require("nvim-surround").setup or require("nvim-surround").buffer_setup with the desired options.

More information on how to configure this plugin can be found in :h nvim-surround.configuration.

Contributing

See the contributing file.

Shoutouts

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