kylechui/nvim-surround

github github
formatting
star 693
stars
alert-circle 7
open issues
users 12
subscribers
git-branch 15
forks
CREATED

2022-04-29

UPDATED

16 minutes ago


nvim-surround

Surround selections, stylishly :sunglasses:

:sparkles: 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

:lock: Requirements

  • Neovim 0.7+
  • [Optional] If nvim-treesitter is installed, then Tree-sitter nodes may be surrounded and modified, in addition to just Vim motions and Lua patterns

:package: Installation

packer.nvim

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

:rocket: 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)
    *make strings               ys$"            "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

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