Getting Started for Beginners

Table of Contents

• The Basics
  • Adding New Surrounds
  • Deleting Surrounds
  • Changing Surrounds

---

The Basics

This plugin serves to help you accomplish three common actions quickly and efficiently:

• Surrounding some selection with a left and right delimiter
• Deleting the surrounding delimiter pair (around the cursor)
• Changing the surrounding delimiter pair (around the cursor) to another pair

nvim-surround's default keymaps are an extension of (Neo)Vim's builtin grammar, where you have [verb][object], e.g. dw for "delete word".

The following examples are all run from Normal mode, unless otherwise specified.

Adding New Surrounds

By default, adding new surrounds is done by the keymap prefix ys, which can be thought of as meaning "you surround". It is used via ys[object][char], where object denotes the text-object that you are surrounding with a delimiter pair defined by char. Consider the example buffer:

local str = "This is a sentence"

If the cursor is on the T and you press ysiw', then "you surround inner word with single quotes", yielding:

local str = "'This' is a sentence"

From here, typing ysa") means "you surround around double quotes with parentheses", yielding:

local str = ("'This' is a sentence")

Surrounds can also be added by first selecting the text in Visual mode, then pressing S[char], e.g. VS].

Deleting Surrounds

By default, deleting surrounding pairs is done by the keymap prefix ds, which can be thought of as meaning "delete surround". It is used via ds[char], where char refers to the pair to be deleted. Consider the example buffer:

require("nvim-surround").setup()

If the cursor is on the - and you press ds", then you "delete surrounding double quotes", yielding:

require(nvim-surround).setup()

From here, typing ds( means "delete surrounding parentheses", yielding:

requirenvim-surround.setup()

Changing Surrounds

By default, changing surrounding pairs is done by the keymap prefix cs, which can be thought of as meaning "change surround". It is used via cs[char1][char2], where char1 refers to the pair to be deleted, and char2 represents the pair to replace it. Consider the example buffer:

local tab = { 'Just', (some), "strings" }

If the cursor is on the J and you press cs'", then you "change surrounding single quotes to double quotes", yielding:

local tab = { "Just", (some), "strings" }

From here, typing cs(" means "change surrounding parentheses to double quotes", yielding:

local tab = { "Just", "some", "strings" }

Note: If there are no pairs that are immediately surrounding the cursor, it can jump to the "nearest pair" (forwards or backwards). See :h nvim-surround.jump for more details.