nvim-surround
A Neovim plugin for adding, changing, and deleting surrounding delimiter pairs like parentheses, quotes, and HTML tags.
What is nvim-surround?
nvim-surround is a Neovim plugin written in Lua that enables users to easily add, change, or delete surrounding delimiter pairs such as parentheses, quotes, and HTML tags. It solves the problem of tedious manual editing when working with nested or paired delimiters in code and text. The plugin provides intuitive keybindings and supports advanced features like dot-repeat actions and Tree-sitter integration.
Neovim users, particularly developers and writers who frequently edit structured text or code and want to improve their editing efficiency. It's especially useful for those familiar with Vim's modal editing and seeking enhanced surround manipulation capabilities.
Developers choose nvim-surround for its modern Lua implementation, seamless integration with Neovim's latest features, and extensive customization options. Its unique selling point includes first-class support for Tree-sitter nodes, buffer-local configurations, and the ability to define powerful custom surrounds using Lua patterns.
Overview
Add/change/delete surrounding delimiter pairs with ease. Written with :heart: in Lua.
Use Cases
Best For
- Quickly wrapping code snippets with parentheses or quotes
- Refactoring HTML/XML tags in markup files
- Changing delimiter types in function calls or arguments
- Manipulating nested structures in configuration files
- Enhancing text editing workflows in Neovim with repeatable actions
- Creating custom surround behaviors for specific file types
Not Ideal For
- Vim users who haven't upgraded to Neovim 0.8 or later
- Editors preferring mouse-based or graphical text manipulation without modal keybindings
- Projects requiring a surround plugin with extensive pre-built surrounds for niche file types without any Lua configuration
- Minimalists seeking ultra-lightweight alternatives like mini.surround over feature-rich plugins
Pros & Cons
Pros
Written in Lua, it integrates seamlessly with Neovim's latest APIs, offering better performance and native support, as indicated by the requirement for Neovim 0.8+.
Supports defining surrounds using Vim motions, Lua patterns, and Tree-sitter nodes, providing flexibility for complex text manipulations, as highlighted in the features list.
Actions can be repeated with Neovim's dot operator, enhancing editing efficiency for repetitive surround tasks, mentioned in the core features.
Allows setting custom mappings and surrounds per buffer, enabling tailored workflows for different file types, as noted in the buffer-local configuration feature.
Cons
Only compatible with Neovim 0.8+, excluding users of traditional Vim or older Neovim versions, which limits its adoption in mixed editor environments.
Customization requires writing Lua code, which can be a barrier for those unfamiliar with Lua or Neovim's Lua API, despite the detailed documentation.
Full features like Tree-sitter node support require installing nvim-treesitter-textobjects, adding setup complexity and potential performance overhead.
Frequently Asked Questions
Related Projects
nvim-treesitterNvim Treesitter configurations and abstraction layer
nvim-treesitter-textobjectsnvim-treesitter-textobjects is a Neovim plugin that leverages Tree-sitter's parsing capabilities to define and manipulate text objects based on the abstract syntax tree (AST) of your code. It enables precise, language-aware editing operations, moving beyond simple regex-based text objects to understand the actual structure of programming languages. ## Key Features - **Syntax-Aware Selection** — Define custom text objects (like `@function.inner` or `@class.outer`) for precise selection within syntactic structures. - **Intelligent Movement** — Jump between text objects (e.g., functions, classes, loops) with mappings that understand code hierarchy. - **Node Swapping** — Swap adjacent syntactic nodes (like parameters or arguments) with simple commands. - **Repeatable Actions** — Make movements repeatable with `;` and `,` for efficient navigation. - **Extensible Queries** — Override or extend built-in textobjects by adding custom Tree-sitter query files. - **Multiple Modes** — Support for charwise, linewise, and blockwise selection modes per text object. ## Philosophy The plugin embraces Tree-sitter's accuracy to provide text objects that are deeply integrated with the language's syntax, offering a more reliable and intuitive editing experience compared to traditional pattern-based approaches.
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.