LuaSnip
v2.3.0
Neovim >= 0.7 (extmarks)
jsregexp for lsp-snippet-transformations (see here for some tips on installing it).
With your preferred plugin manager i.e. vim-plug, Packer or lazy
Packer:
use({
"L3MON4D3/LuaSnip",
-- follow latest release.
tag = "v2.*", -- Replace <CurrentMajor> by the latest released major (first number of latest release)
-- install jsregexp (optional!:).
run = "make install_jsregexp"
})lazy:
{
"L3MON4D3/LuaSnip",
-- follow latest release.
version = "v2.*", -- Replace <CurrentMajor> by the latest released major (first number of latest release)
-- install jsregexp (optional!).
build = "make install_jsregexp"
}vim-plug:
" follow latest release and install jsregexp.
Plug 'L3MON4D3/LuaSnip', {'tag': 'v2.*', 'do': 'make install_jsregexp'} " Replace <CurrentMajor> by the latest released major (first number of latest release)Check the Releases-section to the right for the latest major version.
LuaSnip uses Semantic Versioning (with some leeway, big patches might end up as a Minor version)!
Releases will be tagged as vMajor.Minor.Patch, we recommend following the latest Major release.
Consider watching the repository's releases so you're notified when a new version becomes available.
Note
On Windows, you need to use a shell that can run Unix commands (MinGW,MSYS2,etc).
Luckily, Git offers a sh.exe, so you don't need to install a heavy MSYS2 environment.
Other than Git, you also need a C compiler and make to install jsregexp.
You may also need to change the build command: make install_jsregexp CC=gcc.exe SHELL=C:/path/to/sh.exe .SHELLFLAGS=-c:
SHELL=C:/path/to/Git/usr/bin/sh.exe # if Git/MinGW/MSYS2 `sh.exe` is not in PATH
.SHELLFLAGS=-c # if Git/MinGW/MSYS2 `sh.exe` is not in PATH
CC=gcc.exe # if CC's default value cc is not set (when `which cc` fails to find the compiler command)
NEOVIM_BIN_PATH=C:/path/to/Neovim/bin # if the Makefile fails to automatically detect the Neovim/bin path
In Vim script, with <Tab> for jumping forward/expanding a snippet, <Shift-Tab> for
jumping backward, and <Ctrl-E> for changing the current choice when in a
choiceNode...
" press <Tab> to expand or jump in a snippet. These can also be mapped separately
" via <Plug>luasnip-expand-snippet and <Plug>luasnip-jump-next.
imap <silent><expr> <Tab> luasnip#expand_or_jumpable() ? '<Plug>luasnip-expand-or-jump' : '<Tab>'
" -1 for jumping backwards.
inoremap <silent> <S-Tab> <cmd>lua require'luasnip'.jump(-1)<Cr>
snoremap <silent> <Tab> <cmd>lua require('luasnip').jump(1)<Cr>
snoremap <silent> <S-Tab> <cmd>lua require('luasnip').jump(-1)<Cr>
" For changing choices in choiceNodes (not strictly necessary for a basic setup).
imap <silent><expr> <C-E> luasnip#choice_active() ? '<Plug>luasnip-next-choice' : '<C-E>'
smap <silent><expr> <C-E> luasnip#choice_active() ? '<Plug>luasnip-next-choice' : '<C-E>'... or in Lua, with a different set of keys: <Ctrl-K> for expanding, <Ctrl-L>
for jumping forward, <Ctrl-J> for jumping backward, and <Ctrl-E> for
changing the active choice.
local ls = require("luasnip")
vim.keymap.set({"i"}, "<C-K>", function() ls.expand() end, {silent = true})
vim.keymap.set({"i", "s"}, "<C-L>", function() ls.jump( 1) end, {silent = true})
vim.keymap.set({"i", "s"}, "<C-J>", function() ls.jump(-1) end, {silent = true})
vim.keymap.set({"i", "s"}, "<C-E>", function()
if ls.choice_active() then
ls.change_choice(1)
end
end, {silent = true})nvim-cmp's wiki also contains an example for
setting up a super-tab-like mapping.
Check out the doc for a general explanation of the loaders and their benefits. The following list serves only as a short overview.
VS Code-like: To use existing VS Code style snippets from a plugin (e.g. rafamadriz/friendly-snippets) simply install the plugin and then add
require("luasnip.loaders.from_vscode").lazy_load()somewhere in your Neovim config. LuaSnip will then load the snippets contained in the plugin on startup. You can also easily load your own custom VSCode style snippets by passing the path to the custom snippet-directory to the load function:
-- load snippets from path/of/your/nvim/config/my-cool-snippets
require("luasnip.loaders.from_vscode").lazy_load({ paths = { "./my-cool-snippets" } })For more info on the VS Code loader, check the examples or documentation.
SnipMate-like: Very similar to VS Code packages; install a plugin that provides snippets and call the load-function:
require("luasnip.loaders.from_snipmate").lazy_load()The SnipMate format is very simple, so adding custom snippets only requires a few steps:
init.vim (or any other place that is in your runtimepath) named snippets.<filetype>.snippets and add snippets for the given filetype in it (for inspiration, check honza/vim-snippets).
# comment
snippet <trigger> <description>
<snippet-body>
snippet if C-style if
if ($1)
$0Again, there are some examples and documentation.
Lua: Add the snippets by calling require("luasnip").add_snippets(filetype, snippets). An example for this can be found here.
This can also be done much cleaner, with all the benefits that come with using a loader, by using the loader for Lua
There's also a repository collecting snippets for various languages, molleweide/LuaSnip-snippets.nvim
You have two main choices: use SnipMate/VS Code snippets (easier) or write snippets in Lua (more complex but also more feature-rich). Here are some suggestions for getting started in either case:
DOC.md.
Of those two, SnipMate is definitely the more comfortable way of writing snippets.config: Notable: region_check_events for jumping to the end of snippets the cursor is no longer inside of,
delete_check_events for cleaning up snippets whose text was deleted,
and enable_autosnippets to enable automatic snippet expansion.extras: This module contains many functions that make writing snippets
significantly easier;
fmt and lambda are especially useful.lua-loader:
A very useful way to load snippets, more comfortable than calling add_snippets.functionNode,
dynamicNode,
choiceNode and restoreNode.Note: instead of immediately reading the official documentation, you may want to check out the Resources for new users section below since the docs are written more as a reference manual than as a tutorial for new users.
DOC.md is the main documentation—it gives an overview of how to write snippets, explains the role and use case of each LuaSnip node, shows how to load snippets from Lua, VS Code, and SnipMate formats, and covers the available LuaSnip API.:help luasnip.txt is a plain text version of DOC.md available with Neovim's :help feature.Examples/snippets.lua contains many example snippets written in Lua—we highly recommend looking through (or better yet, :luafileing) these example snippets before using LuaSnip's advanced features.DOC.md as well.【中文版】DOC in Chinese is here.
Here are some LuaSnip videos and tutorials on the Web:
ls.add_snippets instead of with ls.snippets = {}
Inspired by vsnip.vim
